osfmk/ipc/flipc.h

   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
  36 #ifndef _IPC_FLIPC_H_
  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 {
  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
  61         uint32_t            peek_count; // How many kmsgs in mq have been peeked
  62     uint32_t            state:3;    // See FPORT_STATE_* defines below
  63 } *flipc_port_t;
  64
  65 #define FPORT_NULL                      ((flipc_port_t) 0UL)
  66 #define FPORT_VALID(fport)      ((fport) != FPORT_NULL)
  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 {
 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;
 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,
 129                                    uint32_t     flags);
 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,
 136                          mnl_msg_t      msg_arg,
 137                          uint32_t       flags);
 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,
 143                     uint32_t    flags);
 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,
 159                    ipc_mqueue_t mqueue,
 160                    boolean_t    delivered);
 161
 162
 163 __END_DECLS
 164
 165 #endif  // MACH_KERNEL_PRIVATE
 166 #endif  // _IPC_FLIPC_H_
 167