[apple/xnu.git] / osfmk / ipc / flipc.h

/*
 * Copyright (c) 2015-2016 Apple Computer, 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@
 */
/*
 *	File:	ipc/flipc.h
 *	Author:	Dean Reece
 *	Date:	2016
 *
 *	Definitions for fast local ipc (flipc).
 */

#ifndef _IPC_FLIPC_H_
#define _IPC_FLIPC_H_

#if MACH_KERNEL_PRIVATE && MACH_FLIPC

#include <kern/mach_node.h>
#include <ipc/ipc_kmsg.h>
#include <sys/cdefs.h>

__BEGIN_DECLS


/*** FLIPC Port Declarations ***/

/*  A FLIPC port (flipc_port_t) is a companion structure to ipc_port_t.
 *  Any ipc_port object that is known to the flipc layer has one of these
 *  structures to maintain the state of the port with respect to flipc.
 *  When a port reverts to a purely local object (all rights for the port exist
 *  on a single node) the flipc port companion structure will be de-allocated.
 */

typedef struct flipc_port {
	struct mnl_obj          obj;            // Necessary to be in mnl_name_table[]
	ipc_port_t          lport;  // The associated local ipc_port
	mach_node_t                     hostnode;       // Node holding the recieve right
	uint32_t            peek_count; // How many kmsgs in mq have been peeked
	uint32_t            state:3;// See FPORT_STATE_* defines below
} *flipc_port_t;

#define FPORT_NULL                      ((flipc_port_t) 0UL)
#define FPORT_VALID(fport)      ((fport) != FPORT_NULL)

#define FPORT_STATE_INIT            (0) // Port is being initialized
#define FPORT_STATE_PROXY           (1) // Principal is on another node
#define FPORT_STATE_PRINCIPAL       (2) // Principal is on this node
#define FPORT_STATE_PREPRINCIPAL    (3) // Principal moving to this node
#define FPORT_STATE_POSTPRINCIPAL   (4) // Principal moving to other node
#define FPORT_STATE_DEAD            (5) // Port is being destroyed


/*** FLIPC Node Managment Declarations (used by mach node layer) ***/

extern mach_node_id_t   localnode_id;   // This node's FLIPC id.

/*  The mach node layer calls flipc_init() once before it calls any other
 *  flipc entry points.  Returns KERN_SUCCESS on success; otherwise flipc
 *  is not initialized and cannot be used.
 */
kern_return_t flipc_init(void);

/*  flipc_node_prepare() is called by mach node layer when a remote node is
 *  registered by a link driver.  This is the flipc layer's opportunity to
 *  convert it to a flipc port and hook it into any appropriate structures.
 *  Note that the node is not yet in the mach node table.  Returns KERN_SUCCESS
 *  on success; otherwise node is not prepared and cannot be used.
 */
kern_return_t flipc_node_prepare(mach_node_t node);

/*  flipc_node_retire() is called by mach node layer when a remote node is
 *  terminated by a link driver.  This is the flipc layer's opportunity to
 *  convert it back to a local port and unhook it into any structures.
 *  Returns KERN_SUCCESS on success.
 */
kern_return_t flipc_node_retire(mach_node_t node);


/*** FLIPC Message Declarations (used by mach node layer) ***/

/*	Definition for a flipc ack/nak message.  These messages are sent to the
 *  originating node of a message to ack or nak the message.  Ack'd messages
 *  are destroyed by the originating node (to avoid duplicate delivery).  Nak'd
 *  messages are re-sent to the node specified in <resend_to> (used when a
 *  receive right moves to a different node).  These messages are queued onto
 *  the originating node's control_port and sent along with other ipc traffic.
 */

typedef struct flipc_ack_msg {
	struct mnl_msg  mnl;        // Flipc message starts with mnl message
	mach_node_id_t  resend_to;  // Node ID for resends (if NAK)
	uint8_t         msg_count;  // Number of msgs being ackd/nakd
}   __attribute__((__packed__)) * flipc_ack_msg_t;

#define FLIPC_CMD_ID (0x43504952UL) // msgh_id "RIPC" for FLIPC msgs
#define FLIPC_CMD_IPCMESSAGE    (1) // IPC Msg: <node> is sender; <fname> is dest port
#define FLIPC_CMD_ACKMESSAGE    (2) // <fname> is port being ack'd
#define FLIPC_CMD_NAKMESSAGE    (3) // <fname> is port being nak'd


/*  The node layer calls flipc_msg_to_remote_node() to fetch the next message
 *  for <to_node>.  This function will block until a message is available or the
 *  node is terminated, in which case it returns MNL_MSG_NULL.
 */
mnl_msg_t flipc_msg_to_remote_node(mach_node_t  to_node,
    uint32_t     flags);

/*  The node layer calls flipc_msg_to_remote_node() to post the next message
 *  from <from_node>.  This function will block until a message is available
 *  or the node is terminated, in which case it returns MNL_MSG_NULL.
 */
void flipc_msg_from_node(mach_node_t    from_node,
    mnl_msg_t      msg_arg,
    uint32_t       flags);

/*  The node layer calls flipc_msg_free() to dispose of sent messages that
 *  originated in the FLIPC layer.
 */
void flipc_msg_free(mnl_msg_t   msg,
    uint32_t    flags);


/*** FLIPC Message Declarations (used by mach ipc subsystem) ***/

/*	Ack a message sent by <mqueue> to <fport>.  A new kmsg is allocated and
 *  filled in as an ack (or nak if <delivered> is false), then posted to the
 *  node's contol port.  This will wake the link driver (if sleeping) and cause
 *  the ack to be included with normal IPC traffic.
 *
 *  This function immediately returns if <fport> or <node> is invalid, so it
 *  is safe & quick to call speculatively.
 *
 *	Called from mach ipc_mqueue.c when a flipc-originated message is consumed.
 */
void flipc_msg_ack(mach_node_t  node,
    ipc_mqueue_t mqueue,
    boolean_t    delivered);


__END_DECLS

#endif  // MACH_KERNEL_PRIVATE
#endif  // _IPC_FLIPC_H_
Commit	Line	Data
39037602 A	1	/*
	2	* Copyright (c) 2015-2016 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
	5	*
	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. The rights granted to you under the License
	10	* may not be used to create, or enable the creation or redistribution of,
	11	* unlawful or unlicensed copies of an Apple operating system, or to
	12	* circumvent, violate, or enable the circumvention or violation of, any
	13	* terms of an Apple operating system software license agreement.
	14	*
	15	* Please obtain a copy of the License at
	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
	17	*
	18	* The Original Code and all software distributed under the License are
	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	22	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	* Please see the License for the specific language governing rights and
	24	* limitations under the License.
	25	*
	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
	27	*/
	28	/*
	29	* File: ipc/flipc.h
	30	* Author: Dean Reece
	31	* Date: 2016
	32	*
	33	* Definitions for fast local ipc (flipc).
	34	*/
	35
0a7de745	36	#ifndef _IPC_FLIPC_H_
39037602 A	37	#define _IPC_FLIPC_H_
	38
	39	#if MACH_KERNEL_PRIVATE && MACH_FLIPC
	40
	41	#include <kern/mach_node.h>
	42	#include <ipc/ipc_kmsg.h>
	43	#include <sys/cdefs.h>
	44
	45	__BEGIN_DECLS
	46
	47
	48	/* FLIPC Port Declarations */
	49
	50	/* A FLIPC port (flipc_port_t) is a companion structure to ipc_port_t.
	51	* Any ipc_port object that is known to the flipc layer has one of these
	52	* structures to maintain the state of the port with respect to flipc.
	53	* When a port reverts to a purely local object (all rights for the port exist
	54	* on a single node) the flipc port companion structure will be de-allocated.
	55	*/
	56
	57	typedef struct flipc_port {
0a7de745 A	58	struct mnl_obj obj; // Necessary to be in mnl_name_table[]
	59	ipc_port_t lport; // The associated local ipc_port
	60	mach_node_t hostnode; // Node holding the recieve right
39037602	61	uint32_t peek_count; // How many kmsgs in mq have been peeked
0a7de745	62	uint32_t state:3;// See FPORT_STATE_* defines below
39037602 A	63	} *flipc_port_t;
39037602 A	64
0a7de745 A	65	#define FPORT_NULL ((flipc_port_t) 0UL)
0a7de745 A	66	#define FPORT_VALID(fport) ((fport) != FPORT_NULL)
39037602 A	67
	68	#define FPORT_STATE_INIT (0) // Port is being initialized
	69	#define FPORT_STATE_PROXY (1) // Principal is on another node
	70	#define FPORT_STATE_PRINCIPAL (2) // Principal is on this node
	71	#define FPORT_STATE_PREPRINCIPAL (3) // Principal moving to this node
	72	#define FPORT_STATE_POSTPRINCIPAL (4) // Principal moving to other node
	73	#define FPORT_STATE_DEAD (5) // Port is being destroyed
	74
	75
	76	/* FLIPC Node Managment Declarations (used by mach node layer) */
	77
	78	extern mach_node_id_t localnode_id; // This node's FLIPC id.
	79
	80	/* The mach node layer calls flipc_init() once before it calls any other
	81	* flipc entry points. Returns KERN_SUCCESS on success; otherwise flipc
	82	* is not initialized and cannot be used.
	83	*/
	84	kern_return_t flipc_init(void);
	85
	86	/* flipc_node_prepare() is called by mach node layer when a remote node is
	87	* registered by a link driver. This is the flipc layer's opportunity to
	88	* convert it to a flipc port and hook it into any appropriate structures.
	89	* Note that the node is not yet in the mach node table. Returns KERN_SUCCESS
	90	* on success; otherwise node is not prepared and cannot be used.
	91	*/
	92	kern_return_t flipc_node_prepare(mach_node_t node);
	93
	94	/* flipc_node_retire() is called by mach node layer when a remote node is
	95	* terminated by a link driver. This is the flipc layer's opportunity to
	96	* convert it back to a local port and unhook it into any structures.
	97	* Returns KERN_SUCCESS on success.
	98	*/
	99	kern_return_t flipc_node_retire(mach_node_t node);
	100
	101
	102	/* FLIPC Message Declarations (used by mach node layer) */
	103
	104	/* Definition for a flipc ack/nak message. These messages are sent to the
	105	* originating node of a message to ack or nak the message. Ack'd messages
	106	* are destroyed by the originating node (to avoid duplicate delivery). Nak'd
	107	* messages are re-sent to the node specified in <resend_to> (used when a
	108	* receive right moves to a different node). These messages are queued onto
	109	* the originating node's control_port and sent along with other ipc traffic.
	110	*/
	111
	112	typedef struct flipc_ack_msg {
0a7de745 A	113	struct mnl_msg mnl; // Flipc message starts with mnl message
	114	mach_node_id_t resend_to; // Node ID for resends (if NAK)
	115	uint8_t msg_count; // Number of msgs being ackd/nakd
	116	} __attribute__((__packed__)) * flipc_ack_msg_t;
39037602 A	117
	118	#define FLIPC_CMD_ID (0x43504952UL) // msgh_id "RIPC" for FLIPC msgs
	119	#define FLIPC_CMD_IPCMESSAGE (1) // IPC Msg: <node> is sender; <fname> is dest port
	120	#define FLIPC_CMD_ACKMESSAGE (2) // <fname> is port being ack'd
	121	#define FLIPC_CMD_NAKMESSAGE (3) // <fname> is port being nak'd
	122
	123
	124	/* The node layer calls flipc_msg_to_remote_node() to fetch the next message
	125	* for <to_node>. This function will block until a message is available or the
	126	* node is terminated, in which case it returns MNL_MSG_NULL.
	127	*/
	128	mnl_msg_t flipc_msg_to_remote_node(mach_node_t to_node,
0a7de745	129	uint32_t flags);
39037602 A	130
	131	/* The node layer calls flipc_msg_to_remote_node() to post the next message
	132	* from <from_node>. This function will block until a message is available
	133	* or the node is terminated, in which case it returns MNL_MSG_NULL.
	134	*/
	135	void flipc_msg_from_node(mach_node_t from_node,
0a7de745 A	136	mnl_msg_t msg_arg,
0a7de745 A	137	uint32_t flags);
39037602 A	138
	139	/* The node layer calls flipc_msg_free() to dispose of sent messages that
	140	* originated in the FLIPC layer.
	141	*/
	142	void flipc_msg_free(mnl_msg_t msg,
0a7de745	143	uint32_t flags);
39037602 A	144
	145
	146	/* FLIPC Message Declarations (used by mach ipc subsystem) */
	147
	148	/* Ack a message sent by <mqueue> to <fport>. A new kmsg is allocated and
	149	* filled in as an ack (or nak if <delivered> is false), then posted to the
	150	* node's contol port. This will wake the link driver (if sleeping) and cause
	151	* the ack to be included with normal IPC traffic.
	152	*
	153	* This function immediately returns if <fport> or <node> is invalid, so it
	154	* is safe & quick to call speculatively.
	155	*
	156	* Called from mach ipc_mqueue.c when a flipc-originated message is consumed.
	157	*/
	158	void flipc_msg_ack(mach_node_t node,
0a7de745 A	159	ipc_mqueue_t mqueue,
0a7de745 A	160	boolean_t delivered);
39037602 A	161
	162
	163	__END_DECLS
	164
0a7de745 A	165	#endif // MACH_KERNEL_PRIVATE
0a7de745 A	166	#endif // _IPC_FLIPC_H_