osfmk/kern/mach_node_link.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:   kern/mach_node_link.h
  30  *  Author: Dean Reece
  31  *  Date:   2016
  32  *
  33  *  This header provides definitions required by Mach Node Link (MNL) drivers.
  34  *  MNL drivers pass messages between nodes within a host.
  35  *
  36  *  The constructs available at the node link level are very basic:
  37  *  Node IDs (mach_node_id_t) uniquely identify nodes within a host.
  38  *  MNL Info (mnl_node_info) describe the static characteristics of a node.
  39  *  MNL Names (mnl_name_t) uniquely identify abjects across all nodes.
  40  *  MNL Messages (mnl_msg) are passed between nodes (kernels) within a host.
  41  */
  42
  43 #ifndef _KERN_MACH_NODE_LINK_H_
  44 #define _KERN_MACH_NODE_LINK_H_
  45
  46 #if KERNEL_PRIVATE
  47
  48 #include <sys/cdefs.h>
  49
  50 __BEGIN_DECLS
  51
  52
  53 /*** Node Info Section ***/
  54
  55 typedef int             mach_node_id_t; // Used to uniquely identify a node
  56 extern mach_node_id_t   localnode_id;   // This node's unique id.
  57
  58 /*  An mnl_node struct describes static characteristcs of a node.  The link
  59  *  driver requests this structure from the mach_node layer and fills out
  60  *  the fields.  All fields must be filled in (non-zero) before both rx and tx
  61  *  links are brought up.
  62  */
  63 typedef struct mnl_node_info {
  64         mach_node_id_t  node_id;    // The node ID of this node
  65         uint8_t         datamodel;  // 1==ILP32, 2==LP64 (matches dtrace)
  66         uint8_t         byteorder;  // See libkern/OSByteOrder.h
  67         uint32_t        proto_vers_min;// Oldest MNL protocol vers node can accept
  68         uint32_t        proto_vers_max;// Newest MNL protocol vers node can accept
  69 } __attribute__ ((aligned(8))) * mnl_node_info_t;
  70
  71 #define MNL_NODE_NULL       ((mnl_node_info_t) 0UL)
  72 #define MNL_NODE_VALID(n)   ((n) != MNL_NODE_NULL)
  73 #define MNL_PROTOCOL_V1 (1UL)           // Current Node Link Protocol Version
  74
  75 /*** Mach Node Link Name Section
  76  *
  77  *  A node link name (mnl_name_t) is an oqaque value guaranteed unique across
  78  *  kernel instances on all nodes.
  79  */
  80 typedef uint64_t    mnl_name_t;
  81
  82 /*** Mach Node Link Message Section ***/
  83
  84 /*  This structure is the header for an MNL Message buffer; the actual buffer
  85  *  is normally larger, and holds this header followed by the body of the
  86  *  message to be transmitted over the link.
  87  *
  88  *  Note: The <node_id> and <size> fields are in host-native byte order when
  89  *  passed to mnl_msg_from_node() and from mnl_msg_to_node().
  90  *  The byte order of these fields as sent over the link is left to the link
  91  *  specification.  The link drivers on both sides must translate these fields
  92  *  between the link's byte order and host-native byte order.
  93  *
  94  *  The body of the message, however, is treated as a byte-stream and passed
  95  *  to/from the mach_node layer without any introspection or byte reordering.
  96  */
  97 typedef struct mnl_msg {
  98         uint8_t     sub;    //  8b subsystem code
  99         uint8_t     cmd;    //  8b command code
 100         uint8_t     qos;    //  8b TODO: Doesn't do anything yet
 101         uint8_t     flags;  //  8b Command-specific flag byte
 102         uint32_t    node_id;// 32b id of node that originated message
 103         mnl_name_t  object; // 64b object ref (use is determined by sub & cmd)
 104         uint32_t    options;// 32b Currently unused
 105         uint32_t    size;   // 32b Number of bytes that follow mnl_msg header
 106 }  __attribute__((__packed__)) * mnl_msg_t;
 107
 108
 109 /*  Allocate a mnl_msg struct plus additional payload.  Link drivers are not
 110  *  required to use this to allocate messages; any wired and mapped kernel
 111  *  memory is acceptable.
 112  *
 113  *  Arguments:
 114  *    payload   Number of additional bytes to allocate for message payload
 115  *    flags     Currently unused; 0 should be passed
 116  *
 117  *  Return values:
 118  *    MNL_MSG_NULL:     Allocation failed
 119  *    *:                Pointer to new mnl_msg struct of requested size
 120  */
 121 mnl_msg_t mnl_msg_alloc(int payload, uint32_t flags);
 122
 123
 124 /*  Free a mnl_msg struct allocated by mnl_msg_alloc().
 125  *
 126  *  Arguments:
 127  *    msg       Pointer to the message buffer to be freed
 128  *    flags     Currently unused; 0 should be passed
 129  */
 130 void mnl_msg_free(mnl_msg_t msg, uint32_t flags);
 131
 132 #define MNL_MSG_NULL            ((mnl_msg_t) 0UL)
 133 #define MNL_MSG_VALID(msg)      ((msg) != MNL_MSG_NULL)
 134 #define MNL_MSG_SIZE            ((vm_offset_t)sizeof(struct mnl_msg))
 135 #define MNL_MSG_PAYLOAD(msg)    ((vm_offset_t)(msg) + MNL_MSG_SIZE)
 136
 137
 138 /*** Mach Node Link Driver Interface Section ***/
 139
 140 /*  The link driver calls this to setup a new (or restarted) node, and to get
 141  *  an mnl_node_info struct for use as a parameter to other mnl functions.
 142  *  If MNL_NODE_NULL is returned, the operation failed.  Otherwise, a pointer
 143  *  to a new mnl_node struct is returned.  The caller should set all fields
 144  *  in the structure, then call mnl_register() to complete node registration.
 145  *
 146  *  Arguments:
 147  *    nid       The id of the node to be instantiated
 148  *    flags     Currently unused; 0 should be passed
 149  *
 150  *  Return values:
 151  *    MNL_NODE_NULL:    Operation failed
 152  *    *:                Pointer to a new mnl_node struct
 153  */
 154 mnl_node_info_t mnl_instantiate(mach_node_id_t  nid,
 155     uint32_t        flags);
 156
 157
 158 /*  The link driver calls mnl_register() to complete the node registration
 159  *  process.  KERN_SUCCESS is returned if registration succeeded, otherwise
 160  *  an error is returned.
 161  *
 162  *  Arguments:
 163  *    node      Pointer to the node's mnl_node structure
 164  *    flags     Currently unused; 0 should be passed
 165  *
 166  *  Return values:
 167  *    KERN_SUCCESS:           Registration succeeded
 168  *    KERN_INVALID_ARGUMENT:  Field(s) in <node> contained unacceptable values
 169  *    KERN_*:                 Values returned from underlying functions
 170  */
 171 kern_return_t mnl_register(mnl_node_info_t  node,
 172     uint32_t         flags);
 173
 174
 175 /*  The link driver calls this to report that the link has been raised in one
 176  *  or both directions.  If the link is two uni-directional channels, each link
 177  *  driver will independently call this function, each only raising the link
 178  *  they are responsible for.  The mach_node layer will not communicate with
 179  *  the remote node until both rx and tx links are up.
 180  *
 181  *  Arguments:
 182  *    node      Pointer to the node's mnl_node structure
 183  *    link      Indicates which link(s) are up (see MNL_LINK_* defines)
 184  *    flags     Currently unused; 0 should be passed
 185  *
 186  *  Return values:
 187  *    KERN_SUCCESS:           Link state changed successfully.
 188  *    KERN_INVALID_ARGUMENT:  An argument value was not allowed.
 189  *    KERN_*:                 Values returned from underlying functions.
 190  */
 191 kern_return_t mnl_set_link_state(mnl_node_info_t    node,
 192     int                link,
 193     uint32_t           flags);
 194
 195 #define MNL_LINK_DOWN   (0UL)
 196 #define MNL_LINK_RX     (1UL)
 197 #define MNL_LINK_TX     (2UL)
 198 #define MNL_LINK_UP     (MNL_LINK_RX|MNL_LINK_TX)
 199
 200
 201 /*  The link driver calls this to indicate a node has terminated and is no
 202  *  longer available for messaging.  This may be due to a crash or an orderly
 203  *  shutdown, but either way the remote node no longer retains any state about
 204  *  the remaining nodes.  References held on behalf of the terminated node
 205  *  will be cleaned up.  After this is called, both the rx and tx links are
 206  *  marked as down.  If the remote node restarts, the link driver can bring
 207  *  up the link using mnl_instantiate() again.
 208  *
 209  *  Arguments:
 210  *    node      Pointer to the node's mnl_node structure
 211  *    flags     Currently unused; 0 should be passed
 212  *
 213  *  Return values:
 214  *    KERN_SUCCESS:           Node was terminated.
 215  *    KERN_INVALID_ARGUMENT:  Node id was invalid or non-existant.
 216  *    KERN_*:                 Values returned from underlying functions.
 217  */
 218 kern_return_t mnl_terminate(mnl_node_info_t node,
 219     uint32_t        flags);
 220
 221
 222 /*  The link driver calls this to deliver an incoming message.  Note that the
 223  *  link driver must dispose of the memory pointed to by <msg> after the
 224  *  function call returns.
 225  *
 226  *  Arguments:
 227  *    node      Pointer to the node's mnl_node structure
 228  *    msg       Pointer to the message buffer
 229  *    flags     Currently unused; 0 should be passed
 230  */
 231 void mnl_msg_from_node(mnl_node_info_t  node,
 232     mnl_msg_t        msg,
 233     uint32_t         flags);
 234
 235
 236 /*  The link driver calls this to fetch the next message to transmit.
 237  *  This function will block until a message is available, or will return
 238  *  FLIPC_MSG_NULL if the link is to be terminated.  After the caller has
 239  *  completed the transmission and no longer needs the msg buffer, it should
 240  *  call mnl_msg_complete().
 241  *
 242  *  Arguments:
 243  *    node      Pointer to the node's mnl_node structure
 244  *    flags     Currently unused; 0 should be passed
 245  */
 246 mnl_msg_t mnl_msg_to_node(mnl_node_info_t   node,
 247     uint32_t          flags);
 248
 249
 250 /*  The link driver calls this to indicate that the specified msg buffer has
 251  *  been sent over the link and can be deallocated.
 252  *
 253  *  Arguments:
 254  *    node      Pointer to the node's mnl_node structure
 255  *    msg       Pointer to the message buffer
 256  *    flags     Currently unused; 0 should be passed
 257  */
 258 void mnl_msg_complete(mnl_node_info_t   node,
 259     mnl_msg_t         msg,
 260     uint32_t          flags);
 261
 262 __END_DECLS
 263
 264 #endif  /* KERNEL_PRIVATE */
 265 #endif  /* _KERN_MACH_NODE_LINK_H_ */