+/*
+ * Copyright (c) 2018 Apple Inc. All rights reserved.
+ *
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
+ *
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. The rights granted to you under the License
+ * may not be used to create, or enable the creation or redistribution of,
+ * unlawful or unlicensed copies of an Apple operating system, or to
+ * circumvent, violate, or enable the circumvention or violation of, any
+ * terms of an Apple operating system software license agreement.
+ *
+ * Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this file.
+ *
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.
+ *
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
+ */
+#ifndef __MACH_RIGHT_PRIVATE_H
+#define __MACH_RIGHT_PRIVATE_H
+
+#include <os/base.h>
+#include <mach/mach.h>
+#include <mach/port.h>
+#include <mach/mach_port.h>
+#include <sys/cdefs.h>
+#include <stdbool.h>
+
+__BEGIN_DECLS;
+
+/*!
+ * @typedef mach_right_recv_t
+ * A type representing the receive right to a Mach port.
+ */
+typedef struct _mach_right_recv {
+ mach_port_t mrr_name;
+} mach_right_recv_t;
+
+/*!
+ * @const MACH_RIGHT_RECV_NULL
+ * A convenience initializer for a receive right object.
+ */
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
+#define MACH_RIGHT_RECV_NULL ((mach_right_recv_t){MACH_PORT_NULL})
+#elif defined(__cplusplus) && __cplusplus >= 201103L
+#define MACH_RIGHT_RECV_NULL (mach_right_recv_t{MACH_PORT_NULL})
+#elif defined(__cplusplus)
+#define MACH_RIGHT_RECV_NULL \
+ (mach_right_recv_t((mach_right_recv_t){MACH_PORT_NULL}))
+#else
+#define MACH_RIGHT_RECV_NULL {MACH_PORT_NULL}
+#endif
+
+/*!
+ * @typedef mach_right_send_t
+ * A type representing a send right to a Mach port.
+ */
+typedef struct _mach_right_send {
+ mach_port_t mrs_name;
+} mach_right_send_t;
+
+/*!
+ * @const MACH_RIGHT_SEND_NULL
+ * A convenience initializer for a send right object.
+ */
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
+#define MACH_RIGHT_SEND_NULL ((mach_right_send_t){MACH_PORT_NULL})
+#elif defined(__cplusplus) && __cplusplus >= 201103L
+#define MACH_RIGHT_SEND_NULL (mach_right_send_t{MACH_PORT_NULL})
+#elif defined(__cplusplus)
+#define MACH_RIGHT_SEND_NULL \
+ (mach_right_send_t((mach_right_send_t){MACH_PORT_NULL}))
+#else
+#define MACH_RIGHT_SEND_NULL {MACH_PORT_NULL}
+#endif
+
+/*!
+ * @typedef mach_right_send_once_t
+ * A type representing a send-once right to a Mach port.
+ */
+typedef struct _mach_right_send_once {
+ mach_port_t mrso_name;
+} mach_right_send_once_t;
+
+/*!
+ * @const MACH_RIGHT_SEND_ONCE_NULL
+ * A convenience initializer for a send-once right object.
+ */
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
+#define MACH_RIGHT_SEND_ONCE_NULL ((mach_right_send_once_t){MACH_PORT_NULL})
+#elif defined(__cplusplus) && __cplusplus >= 201103L
+#define MACH_RIGHT_SEND_ONCE_NULL (mach_right_send_once_t{MACH_PORT_NULL})
+#elif defined(__cplusplus)
+#define MACH_RIGHT_SEND_ONCE_NULL \
+ (mach_right_send_once_t((mach_right_send_once_t){MACH_PORT_NULL}))
+#else
+#define MACH_RIGHT_SEND_ONCE_NULL {MACH_PORT_NULL}
+#endif
+
+/*!
+ * @function mach_right_recv
+ * Wraps a port name as a receive right object.
+ *
+ * @param pn
+ * The port name. If this name is valid but does not represent a receive right,
+ * the behavior of mach_right_recv_* implementations is undefined.
+ *
+ * @result
+ * A new receive right object.
+ */
+OS_ALWAYS_INLINE OS_WARN_RESULT
+static inline mach_right_recv_t
+mach_right_recv(mach_port_name_t pn)
+{
+ mach_right_recv_t mrr = {pn};
+ return mrr;
+}
+
+/*!
+ * @function mach_right_send
+ * Wraps a port name as a send right object.
+ *
+ * @param pn
+ * The port name. If this name is valid but does not represent a send right, the
+ * behavior of mach_right_send_* implementations is undefined.
+ *
+ * @result
+ * A new send right object.
+ */
+OS_ALWAYS_INLINE OS_WARN_RESULT
+static inline mach_right_send_t
+mach_right_send(mach_port_name_t pn)
+{
+ mach_right_send_t mrs = {pn};
+ return mrs;
+}
+
+/*!
+ * @function mach_right_send_valid
+ * Checks if the given send right object is valid.
+ *
+ * @param mrs
+ * The send right object to check.
+ *
+ * @result
+ * A Boolean indicating whether the right is valid.
+ */
+OS_ALWAYS_INLINE OS_WARN_RESULT
+static inline bool
+mach_right_send_valid(mach_right_send_t mrs)
+{
+ return MACH_PORT_VALID(mrs.mrs_name);
+}
+
+/*!
+ * @function mach_right_send_once
+ * Wraps a port name as a send-once right object.
+ *
+ * @param pn
+ * The port name. If this name is valid but does not represent a send-once
+ * right, the behavior of mach_right_send_once_* implementations is undefined.
+ *
+ * @result
+ * A new send-once right object.
+ */
+OS_ALWAYS_INLINE OS_WARN_RESULT
+static inline mach_right_send_once_t
+mach_right_send_once(mach_port_name_t pn)
+{
+ mach_right_send_once_t mrso = {pn};
+ return mrso;
+}
+
+/*!
+ * @function mach_right_send_once_valid
+ * Checks if the given send-once right object is valid.
+ *
+ * @param mrso
+ * The send-once right object to check.
+ *
+ * @result
+ * A Boolean indicating whether the right is valid.
+ */
+OS_ALWAYS_INLINE OS_WARN_RESULT
+static inline bool
+mach_right_send_once_valid(mach_right_send_once_t mrso)
+{
+ return MACH_PORT_VALID(mrso.mrso_name);
+}
+
+/*!
+ * @typedef mach_right_flags_t
+ * Flags influencing the behavior of a constructed Mach port.
+ *
+ * @const MACH_RIGHT_RECV_INIT
+ * No flags set. This value is suitable for initialization purposes.
+ *
+ * @const MACH_RIGHT_RECV_UNGUARDED
+ * The given context should not serve as a guard for the underlying port's
+ * destruction.
+ */
+OS_ENUM(mach_right_flags, uint64_t,
+ MACH_RIGHT_RECV_FLAG_INIT = 0,
+ MACH_RIGHT_RECV_FLAG_UNGUARDED = (1 << 0),
+);
+
+/*!
+ * @function mach_right_recv_construct
+ * Allocates a new Mach port and returns the receive right to the caller.
+ *
+ * @param flags
+ * Flags to influence the behavior of the new port.
+ *
+ * @param sr
+ * If non-NULL, will be filled in with the name of a send right which
+ * corresponds to the new port. The caller is responsible for disposing of this
+ * send right with {@link mach_right_send_release}.
+ *
+ * @param ctx
+ * Context to be associated with the new port. By default, this context must be
+ * passed to {@link mach_right_recv_destruct} in order to destroy the underlying
+ * port. This requirement may be elided with the
+ * {@link MACH_RIGHT_RECV_UNGUARDED} flag.
+ *
+ * @result
+ * A new port handle which refers to the receive right for the newly-created
+ * port. The caller is responsible for disposing of this handle with
+ * {@link mach_right_recv_destruct}.
+ *
+ * @discussion
+ * The implementation will abort on any failure to allocate a new port object in
+ * the kernel. Thus the caller may assert that a new, valid receive right is
+ * always returned.
+ */
+OS_EXPORT OS_WARN_RESULT
+mach_right_recv_t
+mach_right_recv_construct(mach_right_flags_t flags,
+ mach_right_send_t *_Nullable sr, uintptr_t ctx);
+
+/*!
+ * @function mach_right_recv_destruct
+ * Closes the port referred to by the given receive right.
+ *
+ * @param r
+ * The receive right for the port to manipulate.
+ *
+ * @param s
+ * A pointer to the send right to dispose of. If NULL is given, no attempt will
+ * be made to clean up any send right associated with the port. If the name of
+ * the given send right does not match the name of the given receive right, the
+ * implementation's behavior is undefined.
+ *
+ * @param ctx
+ * The context which guards the underlying port destruction. If the receive
+ * right was created with {@link MACH_RIGHT_RECV_UNGUARDED}, this parameter is
+ * ignored.
+ *
+ * @discussion
+ * If a send right is passed, the implementation performs the moral equivalent
+ * of
+ *
+ * mach_right_recv_destruct(r, MACH_PORT_NULL, ctx);
+ * mach_right_send_release(s);
+ *
+ * except in a more efficient manner, requiring only one system call.
+ *
+ * The implementation will abort on any failure to dispose of the port. As such,
+ * this routine should only be used on ports that are known to be under the
+ * caller's complete control.
+ */
+OS_EXPORT
+void
+mach_right_recv_destruct(mach_right_recv_t r, mach_right_send_t *_Nullable s,
+ uintptr_t ctx);
+
+/*!
+ * @function mach_right_send_create
+ * Creates a send right to the port referenced by the given receive right.
+ *
+ * @param r
+ * The receive right for the port for which to create the send right.
+ *
+ * @result
+ * The name of the new send right. The caller is responsible for disposing of
+ * this send right with {@link mach_right_send_release}.
+ *
+ * This operation will increment the make-send count of the port referenced by
+ * the given receive right.
+ *
+ * @discussion
+ * The implementation will abort on any failure to create the send right. As
+ * such, this routine should only be used on ports that are known to be under
+ * the caller's complete control.
+ */
+OS_EXPORT OS_WARN_RESULT
+mach_right_send_t
+mach_right_send_create(mach_right_recv_t r);
+
+/*!
+ * @function mach_right_send_retain
+ * Increments the user reference count for the given send right.
+ *
+ * @param s
+ * The send right to manipulate.
+ *
+ * @result
+ * If the reference count was successfully incremented, the given port name is
+ * returned. If either MACH_PORT_NULL or MACH_PORT_DEAD are given, the given
+ * value is returned. If the given send right became a dead name before or
+ * during the attempt to retain the send right, MACH_PORT_DEAD is returned.
+ *
+ * If the implementation encounters any other failure condition, it will abort.
+ */
+OS_EXPORT OS_WARN_RESULT
+mach_right_send_t
+mach_right_send_retain(mach_right_send_t s);
+
+/*!
+ * @function mach_right_send_release
+ * Decrements the user reference count for the given send right.
+ *
+ * @param s
+ * The send right to manipulate.
+ *
+ * @discussion
+ * If the given send right became a dead name before or during the attempt to
+ * release it, the implementation will dispose of that dead name.
+ *
+ * If the implementation encounters any other failure condition, it will abort.
+ */
+OS_EXPORT
+void
+mach_right_send_release(mach_right_send_t s);
+
+/*!
+ * @function mach_right_send_once_create
+ * Creates a send-once right from the given receive right.
+ *
+ * @param r
+ * The receive right for the port for which to create the send-once right.
+ *
+ * @result
+ * The newly-created send-once right.
+ *
+ * @discussion
+ * The implementation will abort on any failure to allocate a new send-once
+ * right, and therefore the caller should only provide a receive right which is
+ * under its complete control. The caller may assert that a new, valid send-once
+ * right is always returned.
+ *
+ * The returned send-once right will never share a name with the given receive
+ * right. A send-once right must be consumed either by using it to send a
+ * message or by consuming it with {@link mach_right_send_once_consume}.
+ *
+ * The returned right does not support retain/release semantics despite the
+ * presence of "create" in the name.
+ */
+OS_EXPORT OS_WARN_RESULT
+mach_right_send_once_t
+mach_right_send_once_create(mach_right_recv_t r);
+
+/*!
+ * @function mach_right_send_once_consume
+ * Consumes the given send-once right.
+ *
+ * @param so
+ * The send-once right to manipulate.
+ *
+ * @discussion
+ * If the given send-once right became a dead name before or during the attempt
+ * to release it, the implementation will dispose of that dead name.
+ *
+ * If the implementation encounters any other failure condition, it will abort.
+ *
+ * This operation will cause a send-once notification to be delivered to the
+ * port to which the send-once right refers unless the right is a dead name, in
+ * which case there are no side effects.
+ */
+OS_EXPORT
+void
+mach_right_send_once_consume(mach_right_send_once_t so);
+
+__END_DECLS;
+
+#endif // __MACH_RIGHT_PRIVATE_H
projects / apple / xnu.git / commitdiff
