Mach Kernel Interface Reference Manual

### Mach IPC Interface

> Mach IPC presents itself in a few forms: message queues, lock-sets, and semaphores (more may be added in the future). All share one common charateristic: the capabilities presented by each are represented through a handle known as a Mach port. Specific rights represented in these Mach port capability handles allow the underlying IPC object to be used and manipulated in consistent ways.

> #### Mach Message Queue Interface

> > mach_msg - Send and/or receive a message from the target port.
> > mach_msg_overwrite - Send and/or receive messages with possible overwrite.

> > Mach Message Queue Data Structures

> > mach_msg_descriptor - Specifies an element of a complex IPC message.
> > mach_msg_header - Specifies the content of an IPC message header.

> #### Mach Lock-Set Interface

> > lock_acquire - Acquire ownership a lock
> > lock_handoff - Hand-off ownership of a lock.
> > lock_handoff_accept - Accept lock ownership from a handoff.
> > lock_make_stable - Stabilize the state of the specified lock.
> > lock_release - Release ownership of a lock.
> > lock_set_create - Create a new lock set.
> > lock_set_destroy - Destroy a lock set and its associated locks.
> > lock_try - Attempt to acquire access rights to a lock.

> #### Mach Semaphore Interface

> > semaphore_create - Create a new semaphore.
> > semaphore_destroy - Destroy a semaphore.
> > semaphore_signal - Increments the semaphore count.
> > semaphore_signal_all - Wake up all threads blocked on a semaphore.
> > semaphore_wait - Wait on the specified semaphore.

> #### Mach Port Management Interface

> > mach_port_allocate - Create caller-specified type of port right.
> > mach_port_allocate_full - Create a port right with full Mach port semantics.
> > mach_port_allocate_name - Create a port right with the caller-specified name.
> > mach_port_allocate_qos - Allocate a port with specified "quality of service".
> > mach_port_allocate_subsystem - Create a port right associated with the caller-specified subsystem.
> > mach_port_deallocate - Decrement the target port right's user reference count.
> > mach_port_destroy - Deallocate all port rights associated with specified name.
> > mach_port_extract_right - Remove the specified right from the target task and return it to the caller.
> > mach_port_get_attributes - Return information about target port as specified by the caller.
> > mach_port_get_refs - Return the current count of user references on the target port right.
> > mach_port_get_set_status - Return the port right names contained in the target port set.
> > mach_port_insert_right - Insert the specified port right into the target task.
> > mach_port_mod_refs - Modify the specified port right's count of user references.
> > mach_port_move_member - Move the specified receive right into or out of the specified port set.
> > mach_port_names - Return information about a task's port name space.
> > mach_port_request_notification - Request notification of the specified port event type.
> > mach_port_set_attributes - Set the target port's attributes.
> > mach_port_set_mscount - Change the target port's make-send count.
> > mach_port_set_seqno - Change the current value of the target port's sequence number.
> > mach_port_type - Return the characteristics of the target port name.
> > mach_reply_port - Allocate a new port and insert corresponding receive right in the calling task.
> > mach_subsystem_create - Used by a server to register information about an RPC subsystem with the kernel.

> > Mach Port Data Structures

> > mach_port_limits - Specifies a port's resource and message queue limits.
> > mach_port_qos - Specifies a port's attributes with respect to "Quality Of Service."
> > mach_port_status - Used to present a port's current status with respect to various important attributes.

> > Mach Port Notification Callbacks

> > do_mach_notify_dead_name - Handle the current instance of a dead-name notification.
> > do_mach_notify_no_senders - Handle the current instance of a no-more-senders notification.
> > do_mach_notify_port_deleted - Handle the current instance of a port-deleted notification.
> > do_mach_notify_port_destroyed - Handle the current instance of a port-destroyed notification.
> > do_mach_notify_send_once - Handle the current instance of a send-once notification.

> > Mach Port Notification Callback Server Helpers

> > notify_server - Detect and handle a kernel-generated IPC notification.

### Mach Virtual Memory Interface

> #### Mach Virtual Memory Address Space Manipulation Interface

> > host_page_size - Provide the system's virtual page size.
> > vm_allocate - Allocate a region of virtual memory.
> > vm_behavior_set - Specify expected access patterns for the target VM region.
> > vm_copy - Copy a region of virtual memory.
> > vm_deallocate - Deallocate a region of virtual memory.
> > vm_inherit - Set a VM region's inheritance attribute.
> > vm_machine_attribute - Get/set the target memory region's special attributes.
> > vm_map - Map the specified memory object to a region of virtual memory.
> > vm_msync - Synchronize the specified region of virtual memory.
> > vm_protect - Set access privilege attribute for a region of virtual memory.
> > vm_read - Read the specified range of target task's address space.
> > vm_region - Return description of a virtual memory region.
> > vm_remap - Map memory objects in one address space to that of another's.
> > vm_wire - Modify the target region's paging characteristics.
> > vm_write - Write data to the specified address in the target address space.

> > Data Structures

> > vm_region_basic_info - Defines the attributes of a task's memory region.
> > vm_statistics - Defines statistics for the kernel's use of virtual memory.

> #### External Memory Management Interface

> > The External Memory Management Interface (EMMI) is undergoing significant change in the Darwin system. For this reason, the interface is not currently available to user-level programs. Even for kernel extensions, use of these interfaces in not supported. Instead, the BSD filesystem's Universal Buffer Cache (UBC) mechanism should be used.

> > memory_object_change_attributes - Modify subset of memory object attributes.
> > memory_object_destroy - Shut down a memory object.
> > memory_object_get_attributes - Return current attributes for a memory object.
> > memory_object_lock_request - Restrict access to memory object data.
> > memory_object_synchronize_completed - Synchronized data has been processed.

> > Data Structures

> > memory_object_attr_info - Defines memory object attributes.
> > memory_object_perf_info- Specifies performance-related memory object attributes.

> > External Memory Manager Interface Callbacks

> > memory_object_create - Assign a new memory object to the default memory manager.
> > memory_object_data_initialize - Provide initial data for a new memory object.
> > memory_object_data_request - Request that memory manager page-in specified data.
> > memory_object_data_return - Return memory object data to the appropriate memory manager.
> > memory_object_data_unlock - Request a memory manager release the lock on specific data.
> > memory_object_init - Inform a memory manager on first use of a memory object.
> > memory_object_synchronize - Request synchronization of data with backing store.
> > memory_object_terminate - Relinquish access to a memory object.

> > EMMI Callback Server Helpers

> > memory_object_default_server - Handle kernel operation request targeted for the default pager.
> > memory_object_server - Handle kernel operation request aimed at a given memory manager.

> #### Default Memory Management Interface

> > default_pager_add_segment - Add additional backing storage for a default pager.
> > default_pager_backing_store_create - Create a backing storage object.
> > default_pager_backing_store_delete - Delete a backing storage object.
> > default_pager_backing_store_info - Return information about a backing storage object.
> > default_pager_info - Furnish caller with information about the default pager.
> > default_pager_object_create - Initialize a non-persistent memory object.
> > host_default_memory_manager - Register/Lookup the host's default pager.

### Process Management Interface

> #### Task Interface

> > mach_ports_lookup - Provide caller with an array of the target task's well-known ports.
> > mach_ports_register - Register an array of well-known ports on behalf of the target task.
> > mach_task_self - Return a send right to the caller's task_self port.
> > task_create - Create a new task.
> > task_get_emulation_vector - Return an array identifying the target task's user-level system call handlers.
> > task_get_exception_ports - Return send rights to the target task's exception ports.
> > task_get_special_port - Return a send write to the indicated special port.
> > task_info - Return per-task information according to specified flavor.
> > task_resume - Decrement the target task's suspend count.
> > task_sample - Sample the target task's thread program counters periodically.
> > task_set_emulation - Establish a user-level handler for a system call.
> > task_set_emulation_vector - Establish the target task's user-level system call handlers.
> > task_set_exception_ports - Set target task's exception ports.
> > task_set_info - Set task-specific information state.
> > task_set_port_space - Set the size of the target task's port name space table.
> > task_set_special_port - Set the indicated special port.
> > task_suspend - Suspend the target task.
> > task_swap_exception_ports - Set target task's exception ports, returning the previous exception ports.
> > task_terminate - Terminate the target task and deallocate its resources.
> > task_threads - Return the target task's list of threads.

> > Task Data Structures

> > task_basic_info - Defines basic information for a task.
> > task_thread_times_info - Defines thread execution times information for tasks.

> #### Thread Interface

> > mach_thread_self - Returns the thread self port.
> > thread_abort - Abort a thread.
> > thread_abort_safely - Abort a thread, restartably.
> > thread_create - Create a thread within a task.
> > thread_create_running - Optimized creation of a running thread.
> > thread_depress_abort - Cancel thread scheduling depression.
> > thread_get_exception_ports - Return a send right to an exception port.
> > thread_get_special_port - Return a send right to the caller-specified special port.
> > thread_get_state - Return the execution state for a thread.
> > thread_info - Return information about a thread.
> > thread_resume - Resume a thread.
> > thread_sample - Perform periodic PC sampling for a thread.
> > thread_set_exception_ports - Set exception ports for a thread.
> > thread_set_special_port - Set caller-specified special port belonging to the target thread.
> > thread_set_state - Set the target thread's user-mode execution state.
> > thread_suspend - Suspend a thread.
> > thread_swap_exception_ports - Swap exception ports for a thread.
> > thread_terminate - Destroy a thread.
> > thread_wire - Mark the thread as privileged with respect to kernel resources.

> > Thread Data Structures

> > thread_basic_info - Defines basic information for a thread.

> > Thread Exception Callbacks

> > catch_exception_raise - Handles the occurrence of an exception within a thread.

> > Thread Exception Callback Server Helpers

> > exc_server - Handle kernel-reported thread exception.

> #### Scheduling Interface

> > task_policy - Set target task's default scheduling policy state.
> > task_set_policy - Set target task's default scheduling policy state.
> > thread_policy - Set target thread's scheduling policy state.
> > thread_set_policy - Set target thread's scheduling policy state.
> > thread_switch - Cause context switch with options.

> > Scheduling Data Structures

> > policy_fifo_info - Specifies information associated with the system's First-In-First-Out scheduling policy.
> > policy_rr_info - Specifies information associated with the system's Round Robin scheduling policy.
> > policy_timeshare_info - Specifies information associated with the system's Timeshare scheduling policy.

### System Management Interface

> #### Host Interface

> > host_get_clock_service - Return a send right to a kernel clock's service port.
> > host_get_time - Returns the current time as seen by that host.
> > host_info - Return information about a host.
> > host_kernel_version - Return kernel version information for a host.
> > host_statistics - Return statistics for a host.
> > mach_host_self - Returns send rights to the task's host self port.

> > Data Structures

> > host_basic_info - Used to present basic information about a host.
> > host_load_info - Used to present a host's processor load information.
> > host_sched_info - - Used to present the set of scheduler limits associated with the host.
> > kernel_resource_sizes - Used to present the sizes of kernel's major structures.

> #### Host Control Interface

> > host_adjust_time - Arranges for the time on a specified host to be gradually changed by an adjustment value.
> > host_default_memory_manager - Set the default memory manager.
> > host_get_boot_info - Return operator boot information.
> > host_get_clock_control - Return a send right to a kernel clock's control port.
> > host_processor_slots - Return a list of numbers that map processor slots to active processors.
> > host_processors - Return a list of send rights representing all processor ports.
> > host_reboot - Reboot this host.
> > host_set_time - Establishes the time on the specified host.

> #### Host Security Interface

> > task_create_security_token - Create a new task with an explicit security token.
> > task_set_security_token - Change the target task's security token.

> #### Resource Accounting Interface

> > The Mach resource accounting mechanism is not functional in the current Mac OS X/Darwin system. It will become functional in a future release.

> > ledger_create - Create a subordinate ledger.
> > ledger_read - Return the ledger limit and balance.
> > ledger_terminate - Destroy a ledger.
> > ledger_transfer - Transfer resources from a parent ledger to a child.

> #### Processor Management Interface

> > processor_control - Perform caller-specified operation on target processor.
> > processor_exit - Exit a processor.
> > processor_info - Return information about a processor.
> > processor_start - Start a processor.

> > Processor Data Structures

> > processor_basic_info - Defines the basic information about a processor.

> #### Processor Set Interface

> > The processor set interface allows for the grouping of tasks and processors for the purpose of exclusive scheduling. These interface are deprecated and should not be used in code that isn't tied to a particular release of Mac OS X/Darwin. These will likely change or disappear in a future release.

> > host_processor_sets - Return a list of send rights representing all processor set name ports.
> > host_processor_set_priv - Translate a processor set name port into a processor set control port.
> > processor_assign - Assign a processor to a processor set.
> > processor_get_assignment - Get current assignment for a processor.
> > processor_set_create - Create a new processor set.
> > processor_set_default - Return the default processor set.
> > processor_set_destroy - Destroy the target processor set.
> > processor_set_info - Return processor set state according to caller-specified flavor.
> > processor_set_max_priority - Sets the maximum scheduling priority for a processor set.
> > processor_set_policy_control - Set target processor set's scheduling policy state.
> > processor_set_policy_disable - Enables a scheduling policy for a processor set.
> > processor_set_policy_enable - Enables a scheduling policy for a processor set.
> > processor_set_statistics - Return scheduling statistics for a processor set.
> > processor_set_tasks - Return all tasks currently assigned to the target processor set.
> > processor_set_threads - Return all threads currently assigned to the target processor set.
> > task_assign - Assign a task to a processor set.
> > task_assign_default - Assign a task to the default processor set.
> > task_get_assignment - Create a new task with an explicit security token.
> > thread_assign - Assign a thread to a processor set.
> > thread_assign_default - Assign a thread to the default processor set.
> > thread_get_assignment - Return the processor set to which a thread is assigned.

> > Processor Set Data Structures

> > processor_set_basic_info - Defines the basic information about a processor set.
> > processor_set_load_info - Defines the scheduling statistics for a processor set.

> #### Clock Interface

> > clock_alarm - Set up an alarm.
> > clock_get_attributes - Return attributes of a clock.
> > clock_get_time - Return the current time.
> > clock_map_time - Return a memory object that maps a clock.
> > clock_set_attributes - Set a particular clock's attributes.
> > clock_set_time - Set the current time.
> > clock_sleep - Delay the invoking thread until a specified time.

> > Clock Data Structures

> > mapped_tvalspec - Specifies the format the kernel uses to maintain a mapped clock's time.
> > tvalspec - Defines format of system time values.

> > Clock Interface Callbacks

> > clock_alarm_reply - Ring a preset alarm.

> > Clock Callback Server Helpers

> > clock_reply_server - Handle kernel-generated alarm.

> #### Multi-Computer Support Interface

> > These multi-computer support interfaces are no longer supported by the Mac OS X/Darwin kernel. If and when multi-computer support is added back in, something like these will likely be added.

> > host_page_size - Returns the page size for the given host.
> > ledger_get_remote - Return send right to specified host's remote ledger port.
> > ledger_set_remote - Set this host's remote ledger port.
> > norma_get_special_port - Returns a send right for a specified node-specific special port.
> > norma_node_self - Return the node index of the current host.
> > norma_port_location_hint - Guess a port's current location.
> > norma_set_special_port - Set node-specific special port.
> > norma_task_clone - Create a remote task that shares access to parent task's memory.
> > norma_task_create - Create a remote task using task_create semantics.
> > norma_task_teleport - "Clone" a task on a specified node.

### Machine Specific Interface

> #### Intel 386 Support

> > i386_get_ldt - Returns per-thread segment descriptors from the local descriptor table (LDT).
> > i386_io_port_add - Adds a device to the I/O permission bitmap for a thread.
> > i386_io_port_list - Returns a list of the devices named in the thread's I/O permission bitmap.
> > i386_io_port_remove - Removes the specified device from the thread's I/O permission bitmap.
> > i386_set_ldt - Allows a thread to have a private local descriptor table (LDT).

> #### PowerPC Support