From 13fec9890cf095cc781fdf7b8917cb03bf32dd4c Mon Sep 17 00:00:00 2001 From: Apple <opensource@apple.com> Date: Mon, 7 Aug 2006 22:20:11 +0000 Subject: [PATCH] xnu-792.6.76.tar.gz --- bsd/crypto/aes/aes.h | 350 ++-- bsd/crypto/aes/aescrypt.c | 822 ++++----- bsd/crypto/aes/aeskey.c | 910 +++++----- bsd/crypto/aes/aesopt.h | 1506 ++++++++--------- bsd/crypto/aes/aestab.c | 768 ++++----- bsd/crypto/aes/aestab.h | 350 ++-- bsd/dev/ppc/kern_machdep.c | 4 +- bsd/hfs/hfs_search.c | 19 +- bsd/hfs/hfs_vfsutils.c | 2 + bsd/kern/kern_aio.c | 14 +- bsd/kern/kern_mman.c | 4 +- bsd/kern/kern_prot.c | 78 +- bsd/kern/ubc_subr.c | 31 + bsd/kern/uipc_socket2.c | 11 +- bsd/kern/uipc_usrreq.c | 9 +- bsd/miscfs/devfs/index.html | 44 +- bsd/net/ether_inet_pr_module.c | 4 +- bsd/net/kpi_interface.c | 10 +- bsd/net/ndrv.c | 3 + bsd/netat/ddp_lap.c | 2 +- bsd/netinet/ip_dummynet.c | 3 +- bsd/netinet/ip_fw2.c | 1 + bsd/netinet/ip_icmp.c | 13 + bsd/netinet/ip_input.c | 8 +- bsd/netinet6/ip6_forward.c | 7 + bsd/netinet6/ip6_output.c | 7 +- bsd/netinet6/ipsec.c | 8 +- bsd/nfs/nfs_vnops.c | 10 +- bsd/sys/file_internal.h | 3 +- bsd/sys/ubc.h | 2 + bsd/ufs/ufs/ufs_vnops.c | 16 +- bsd/vfs/vfs_utfconv.c | 76 + bsd/vfs/vfs_utfconvdata.h | 678 ++++++++ bsd/vfs/vfs_vnops.c | 14 +- bsd/vm/dp_backing_file.c | 2 +- bsd/vm/vm_unix.c | 10 +- config/BSDKernel.exports | 1 + config/MasterVersion | 2 +- iokit/bsddev/DINetBootHook.cpp | 2 +- iokit/bsddev/DINetBootHook.h | 2 +- libkern/libkern/OSCrossEndian.h | 8 +- osfmk/man/DMN_port_deleted.html | 66 +- osfmk/man/DMN_port_destroyed.html | 60 +- osfmk/man/DP_backing_store_create.html | 63 +- osfmk/man/DP_backing_store_delete.html | 49 +- osfmk/man/DP_backing_store_info.html | 75 +- osfmk/man/DP_object_create.html | 73 +- osfmk/man/DR_overwrite_async.html | 72 +- osfmk/man/HD_memory_manager.html | 48 +- osfmk/man/MO_SY_completed.html | 51 +- osfmk/man/MO_change_attributes.html | 89 +- osfmk/man/MO_change_completed.html | 68 +- osfmk/man/MO_data_initialize.html | 80 +- osfmk/man/MO_data_unavailable.html | 68 +- osfmk/man/MO_default_server.html | 63 +- osfmk/man/MO_get_attributes.html | 74 +- osfmk/man/MO_lock_completed.html | 96 +- osfmk/man/MO_supply_completed.html | 105 +- osfmk/man/MP_allocate_subsystem.html | 75 +- osfmk/man/MP_request_notification.html | 148 +- osfmk/man/P_set_policy_control.html | 92 +- osfmk/man/P_set_policy_disable.html | 51 +- osfmk/man/P_set_policy_enable.html | 39 +- osfmk/man/SMO_default_server.html | 68 +- osfmk/man/SMO_server.html | 68 +- osfmk/man/TS_exception_ports.html | 186 +- osfmk/man/VSD_memory_manager.html | 45 +- osfmk/man/bootstrap_arguments.html | 57 +- osfmk/man/bootstrap_completed.html | 60 +- osfmk/man/bootstrap_environment.html | 57 +- osfmk/man/bootstrap_ports.html | 76 +- osfmk/man/catch_exception_raise.html | 242 ++- osfmk/man/clock_alarm.html | 80 +- osfmk/man/clock_alarm_reply.html | 81 +- osfmk/man/clock_get_attributes.html | 80 +- osfmk/man/clock_get_time.html | 46 +- osfmk/man/clock_map_time.html | 52 +- osfmk/man/clock_reply_server.html | 50 +- osfmk/man/clock_set_attributes.html | 69 +- osfmk/man/clock_set_time.html | 49 +- osfmk/man/clock_sleep.html | 80 +- osfmk/man/default_pager_add_segment.html | 81 +- osfmk/man/default_pager_info.html | 59 +- osfmk/man/device_close.html | 42 +- osfmk/man/device_get_status.html | 63 +- osfmk/man/device_map.html | 107 +- osfmk/man/device_open.html | 113 +- osfmk/man/device_read.html | 101 +- osfmk/man/device_read_async.html | 68 +- osfmk/man/device_read_async_inband.html | 69 +- osfmk/man/device_read_inband.html | 101 +- osfmk/man/device_read_overwrite.html | 102 +- osfmk/man/device_reply_server.html | 59 +- osfmk/man/device_set_filter.html | 195 ++- osfmk/man/device_set_status.html | 71 +- osfmk/man/device_write.html | 99 +- osfmk/man/device_write_async.html | 70 +- osfmk/man/device_write_async_inband.html | 72 +- osfmk/man/device_write_inband.html | 98 +- osfmk/man/do_mach_notify_dead_name.html | 66 +- osfmk/man/do_mach_notify_no_senders.html | 56 +- osfmk/man/do_mach_notify_send_once.html | 49 +- osfmk/man/etap_get_info.html | 94 +- osfmk/man/etap_probe.html | 64 +- osfmk/man/etap_trace_event.html | 109 +- osfmk/man/etap_trace_thread.html | 50 +- osfmk/man/evc_wait.html | 51 +- osfmk/man/exc_server.html | 61 +- osfmk/man/host_adjust_time.html | 43 +- osfmk/man/host_basic_info.html | 87 +- osfmk/man/host_get_boot_info.html | 38 +- osfmk/man/host_get_clock_control.html | 65 +- osfmk/man/host_get_clock_service.html | 69 +- osfmk/man/host_get_time.html | 39 +- osfmk/man/host_info.html | 81 +- osfmk/man/host_kernel_version.html | 42 +- osfmk/man/host_load_info.html | 48 +- osfmk/man/host_page_size.html | 35 +- osfmk/man/host_processor_set_priv.html | 49 +- osfmk/man/host_processor_sets.html | 53 +- osfmk/man/host_processor_slots.html | 47 +- osfmk/man/host_processors.html | 47 +- osfmk/man/host_reboot.html | 36 +- osfmk/man/host_sched_info.html | 40 +- .../man/host_security_create_task_token.html | 74 +- osfmk/man/host_security_set_task_token.html | 61 +- osfmk/man/host_set_time.html | 38 +- osfmk/man/host_statistics.html | 66 +- osfmk/man/i386_get_ldt.html | 50 +- osfmk/man/i386_io_port_add.html | 47 +- osfmk/man/i386_io_port_list.html | 39 +- osfmk/man/i386_io_port_remove.html | 39 +- osfmk/man/i386_set_ldt.html | 91 +- osfmk/man/index.html | 456 ++++- osfmk/man/io_done_queue_create.html | 49 +- osfmk/man/io_done_queue_terminate.html | 42 +- osfmk/man/io_done_queue_wait.html | 62 +- osfmk/man/kernel_resource_sizes.html | 51 +- osfmk/man/ledger_create.html | 70 +- osfmk/man/ledger_get_remote.html | 81 +- osfmk/man/ledger_read.html | 48 +- osfmk/man/ledger_set_remote.html | 40 +- osfmk/man/ledger_terminate.html | 36 +- osfmk/man/ledger_transfer.html | 52 +- osfmk/man/lock_acquire.html | 62 +- osfmk/man/lock_handoff.html | 64 +- osfmk/man/lock_handoff_accept.html | 67 +- osfmk/man/lock_make_stable.html | 56 +- osfmk/man/lock_release.html | 56 +- osfmk/man/lock_set_create.html | 74 +- osfmk/man/lock_set_destroy.html | 59 +- osfmk/man/lock_try.html | 63 +- osfmk/man/mach_host_self.html | 29 +- osfmk/man/mach_msg.html | 988 ++++++++++- osfmk/man/mach_msg_descriptor.html | 117 +- osfmk/man/mach_msg_header.html | 184 +- osfmk/man/mach_port_allocate.html | 85 +- osfmk/man/mach_port_allocate_full.html | 97 +- osfmk/man/mach_port_allocate_name.html | 80 +- osfmk/man/mach_port_allocate_qos.html | 66 +- osfmk/man/mach_port_deallocate.html | 58 +- osfmk/man/mach_port_destroy.html | 72 +- osfmk/man/mach_port_extract_member.html | 90 +- osfmk/man/mach_port_extract_right.html | 75 +- osfmk/man/mach_port_get_attributes.html | 86 +- osfmk/man/mach_port_get_refs.html | 79 +- osfmk/man/mach_port_get_set_status.html | 72 +- osfmk/man/mach_port_insert_member.html | 84 +- osfmk/man/mach_port_insert_right.html | 102 +- osfmk/man/mach_port_limits.html | 35 +- osfmk/man/mach_port_mod_refs.html | 109 +- osfmk/man/mach_port_move_member.html | 96 +- osfmk/man/mach_port_names.html | 71 +- osfmk/man/mach_port_qos.html | 47 +- osfmk/man/mach_port_set_attributes.html | 79 +- osfmk/man/mach_port_set_mscount.html | 58 +- osfmk/man/mach_port_set_seqno.html | 61 +- osfmk/man/mach_port_status.html | 96 +- osfmk/man/mach_port_type.html | 80 +- osfmk/man/mach_ports_lookup.html | 50 +- osfmk/man/mach_ports_register.html | 116 +- osfmk/man/mach_reply_port.html | 52 +- osfmk/man/mach_rpc_return_trap.html | 34 +- osfmk/man/mach_rpc_trap.html | 84 +- osfmk/man/mach_subsystem_create.html | 89 +- osfmk/man/mach_task_self.html | 32 +- osfmk/man/mach_thread_self.html | 28 +- osfmk/man/mapped_tvalspec.html | 55 +- osfmk/man/memory_object_attr_info.html | 85 +- osfmk/man/memory_object_create.html | 120 +- osfmk/man/memory_object_data_error.html | 71 +- osfmk/man/memory_object_data_request.html | 114 +- osfmk/man/memory_object_data_return.html | 103 +- osfmk/man/memory_object_data_supply.html | 141 +- osfmk/man/memory_object_data_unlock.html | 97 +- osfmk/man/memory_object_destroy.html | 54 +- osfmk/man/memory_object_init.html | 77 +- osfmk/man/memory_object_lock_request.html | 174 +- osfmk/man/memory_object_perf_info.html | 54 +- osfmk/man/memory_object_server.html | 64 +- osfmk/man/memory_object_synchronize.html | 107 +- osfmk/man/memory_object_terminate.html | 68 +- osfmk/man/norma_get_special_port.html | 103 +- osfmk/man/norma_node_self.html | 33 +- osfmk/man/norma_port_location_hint.html | 45 +- osfmk/man/norma_set_special_port.html | 98 +- osfmk/man/norma_task_clone.html | 79 +- osfmk/man/norma_task_create.html | 60 +- osfmk/man/norma_task_teleport.html | 72 +- osfmk/man/notify_server.html | 55 +- osfmk/man/policy_fifo_info.html | 76 +- osfmk/man/policy_rr_info.html | 82 +- osfmk/man/policy_timeshare_info.html | 89 +- osfmk/man/processor_assign.html | 60 +- osfmk/man/processor_basic_info.html | 48 +- osfmk/man/processor_control.html | 52 +- osfmk/man/processor_exit.html | 45 +- osfmk/man/processor_get_assignment.html | 41 +- osfmk/man/processor_info.html | 63 +- osfmk/man/processor_set_basic_info.html | 37 +- osfmk/man/processor_set_create.html | 50 +- osfmk/man/processor_set_default.html | 40 +- osfmk/man/processor_set_destroy.html | 37 +- osfmk/man/processor_set_info.html | 104 +- osfmk/man/processor_set_load_info.html | 46 +- osfmk/man/processor_set_max_priority.html | 48 +- osfmk/man/processor_set_statistics.html | 54 +- osfmk/man/processor_set_tasks.html | 42 +- osfmk/man/processor_set_threads.html | 42 +- osfmk/man/processor_start.html | 47 +- osfmk/man/prof_server.html | 50 +- osfmk/man/receive_samples.html | 52 +- osfmk/man/semaphore_create.html | 79 +- osfmk/man/semaphore_destroy.html | 59 +- osfmk/man/semaphore_signal.html | 50 +- osfmk/man/semaphore_signal_all.html | 43 +- osfmk/man/semaphore_wait.html | 53 +- osfmk/man/seqnos_notify_server.html | 59 +- osfmk/man/task_assign.html | 50 +- osfmk/man/task_assign_default.html | 50 +- osfmk/man/task_basic_info.html | 64 +- osfmk/man/task_create.html | 125 +- osfmk/man/task_get_assignment.html | 40 +- osfmk/man/task_get_emulation_vector.html | 55 +- osfmk/man/task_get_exception_ports.html | 141 +- osfmk/man/task_get_special_port.html | 105 +- osfmk/man/task_info.html | 118 +- osfmk/man/task_policy.html | 76 +- osfmk/man/task_resume.html | 40 +- osfmk/man/task_sample.html | 42 +- osfmk/man/task_set_emulation.html | 47 +- osfmk/man/task_set_emulation_vector.html | 62 +- osfmk/man/task_set_exception_ports.html | 139 +- osfmk/man/task_set_info.html | 45 +- osfmk/man/task_set_policy.html | 81 +- osfmk/man/task_set_port_space.html | 38 +- osfmk/man/task_set_special_port.html | 111 +- osfmk/man/task_suspend.html | 42 +- osfmk/man/task_swap_exception_ports.html | 177 +- osfmk/man/task_terminate.html | 36 +- osfmk/man/task_thread_times_info.html | 42 +- osfmk/man/task_threads.html | 47 +- osfmk/man/thread_abort.html | 128 +- osfmk/man/thread_abort_safely.html | 135 +- osfmk/man/thread_activation_create.html | 80 +- osfmk/man/thread_assign.html | 43 +- osfmk/man/thread_assign_default.html | 41 +- osfmk/man/thread_basic_info.html | 101 +- osfmk/man/thread_create.html | 59 +- osfmk/man/thread_create_running.html | 74 +- osfmk/man/thread_depress_abort.html | 30 +- osfmk/man/thread_get_assignment.html | 41 +- osfmk/man/thread_get_exception_ports.html | 142 +- osfmk/man/thread_get_special_port.html | 77 +- osfmk/man/thread_get_state.html | 58 +- osfmk/man/thread_info.html | 89 +- osfmk/man/thread_policy.html | 74 +- osfmk/man/thread_resume.html | 42 +- osfmk/man/thread_sample.html | 44 +- osfmk/man/thread_set_exception_ports.html | 144 +- osfmk/man/thread_set_policy.html | 83 +- osfmk/man/thread_set_special_port.html | 60 +- osfmk/man/thread_set_state.html | 56 +- osfmk/man/thread_suspend.html | 58 +- osfmk/man/thread_switch.html | 125 +- osfmk/man/thread_terminate.html | 32 +- osfmk/man/thread_wire.html | 54 +- osfmk/man/tvalspec.html | 45 +- osfmk/man/vm_allocate.html | 107 +- osfmk/man/vm_behavior_set.html | 89 +- osfmk/man/vm_copy.html | 73 +- osfmk/man/vm_deallocate.html | 68 +- osfmk/man/vm_inherit.html | 96 +- osfmk/man/vm_machine_attribute.html | 113 +- osfmk/man/vm_map.html | 226 ++- osfmk/man/vm_msync.html | 84 +- osfmk/man/vm_protect.html | 111 +- osfmk/man/vm_read.html | 88 +- osfmk/man/vm_region.html | 97 +- osfmk/man/vm_region_basic_info.html | 81 +- osfmk/man/vm_remap.html | 194 ++- osfmk/man/vm_statistics.html | 99 +- osfmk/man/vm_wire.html | 92 +- osfmk/man/vm_write.html | 69 +- osfmk/ppc/lowmem_vectors.s | 88 +- osfmk/ppc/machine_routines_asm.s | 2 +- osfmk/ppc/mappings.c | 13 + osfmk/ppc/pmap.h | 1 + 308 files changed, 23618 insertions(+), 2766 deletions(-) diff --git a/bsd/crypto/aes/aes.h b/bsd/crypto/aes/aes.h index d2dd335c3..8f8cefe0f 100644 --- a/bsd/crypto/aes/aes.h +++ b/bsd/crypto/aes/aes.h @@ -1,175 +1,175 @@ -/* - --------------------------------------------------------------------------- - Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. - - LICENSE TERMS - - The free distribution and use of this software in both source and binary - form is allowed (with or without changes) provided that: - - 1. distributions of this source code include the above copyright - notice, this list of conditions and the following disclaimer; - - 2. distributions in binary form include the above copyright - notice, this list of conditions and the following disclaimer - in the documentation and/or other associated materials; - - 3. the copyright holder's name is not used to endorse products - built using this software without specific written permission. - - ALTERNATIVELY, provided that this notice is retained in full, this product - may be distributed under the terms of the GNU General Public License (GPL), - in which case the provisions of the GPL apply INSTEAD OF those given above. - - DISCLAIMER - - This software is provided 'as is' with no explicit or implied warranties - in respect of its properties, including, but not limited to, correctness - and/or fitness for purpose. - --------------------------------------------------------------------------- - Issue 28/01/2004 - - This file contains the definitions required to use AES in C. See aesopt.h - for optimisation details. -*/ - -#if !defined( _AES_H ) -#define _AES_H - -/* This include is used to find 8 & 32 bit unsigned integer types */ -#include <machine/limits.h> - -#if defined(__cplusplus) -extern "C" -{ -#endif - -#define AES_128 /* define if AES with 128 bit keys is needed */ -#define AES_192 /* define if AES with 192 bit keys is needed */ -#define AES_256 /* define if AES with 256 bit keys is needed */ -#define AES_VAR /* define if a variable key size is needed */ - -/* The following must also be set in assembler files if being used */ - -#define AES_ENCRYPT /* if support for encryption is needed */ -#define AES_DECRYPT /* if support for decryption is needed */ -//#define AES_ERR_CHK /* for parameter checks & error return codes */ - -#if UCHAR_MAX == 0xff /* an unsigned 8 bit type */ - typedef unsigned char aes_08t; -#else -# error Please define aes_08t as an 8-bit unsigned integer type in aes.h -#endif - -#if UINT_MAX == 4294967295 /* an unsigned 32 bit type */ - typedef unsigned int aes_32t; -#elif ULONG_MAX == 4294967295ul - typedef unsigned long aes_32t; -#else -# error Please define aes_32t as a 32-bit unsigned integer type in aes.h -#endif - -#define AES_BLOCK_SIZE 16 /* the AES block size in bytes */ -#define N_COLS 4 /* the number of columns in the state */ - -/* The key schedule length is 11, 13 or 15 16-byte blocks for 128, */ -/* 192 or 256-bit keys respectively. That is 176, 208 or 240 bytes */ -/* or 44, 52 or 60 32-bit words. For simplicity this code allocates */ -/* the maximum 60 word array for the key schedule for all key sizes */ - -#if defined( AES_VAR ) || defined( AES_256 ) -#define KS_LENGTH 60 -#elif defined( AES_192 ) -#define KS_LENGTH 52 -#else -#define KS_LENGTH 44 -#endif - -#if defined( AES_ERR_CHK ) -#define aes_ret int -#define aes_good 0 -#define aes_error -1 -#else -#define aes_ret void -#endif - -#if !defined( AES_DLL ) /* implement normal/DLL functions */ -#define aes_rval aes_ret -#else -#define aes_rval aes_ret __declspec(dllexport) _stdcall -#endif - -typedef struct -{ aes_32t ks[KS_LENGTH]; - aes_32t rn; -} aes_encrypt_ctx; - -typedef struct -{ aes_32t ks[KS_LENGTH]; - aes_32t rn; -} aes_decrypt_ctx; - -typedef struct -{ - aes_decrypt_ctx decrypt; - aes_encrypt_ctx encrypt; -} aes_ctx; - - -/* This routine must be called before first use if non-static */ -/* tables are being used */ - -void gen_tabs(void); - -/* The key length (klen) is input in bytes when it is in the range */ -/* 16 <= klen <= 32 or in bits when in the range 128 <= klen <= 256 */ - -#if defined( AES_ENCRYPT ) - -#if defined(AES_128) || defined(AES_VAR) -aes_rval aes_encrypt_key128(const unsigned char *in_key, aes_encrypt_ctx cx[1]); -#endif - -#if defined(AES_192) || defined(AES_VAR) -aes_rval aes_encrypt_key192(const unsigned char *in_key, aes_encrypt_ctx cx[1]); -#endif - -#if defined(AES_256) || defined(AES_VAR) -aes_rval aes_encrypt_key256(const unsigned char *in_key, aes_encrypt_ctx cx[1]); -#endif - -#if defined(AES_VAR) -aes_rval aes_encrypt_key(const unsigned char *in_key, int key_len, aes_encrypt_ctx cx[1]); -#endif - -aes_rval aes_encrypt_cbc(const unsigned char *in_blk, const unsigned char *in_iv, unsigned int num_blk, - unsigned char *out_blk, const aes_encrypt_ctx cx[1]); -#endif - -#if defined( AES_DECRYPT ) - -#if defined(AES_128) || defined(AES_VAR) -aes_rval aes_decrypt_key128(const unsigned char *in_key, aes_decrypt_ctx cx[1]); -#endif - -#if defined(AES_192) || defined(AES_VAR) -aes_rval aes_decrypt_key192(const unsigned char *in_key, aes_decrypt_ctx cx[1]); -#endif - -#if defined(AES_256) || defined(AES_VAR) -aes_rval aes_decrypt_key256(const unsigned char *in_key, aes_decrypt_ctx cx[1]); -#endif - -#if defined(AES_VAR) -aes_rval aes_decrypt_key(const unsigned char *in_key, int key_len, aes_decrypt_ctx cx[1]); -#endif - -aes_rval aes_decrypt_cbc(const unsigned char *in_blk, const unsigned char *in_iv, unsigned int num_blk, - unsigned char *out_blk, const aes_decrypt_ctx cx[1]); -#endif - -#if defined(__cplusplus) -} -#endif - -#endif +/* + --------------------------------------------------------------------------- + Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. + + LICENSE TERMS + + The free distribution and use of this software in both source and binary + form is allowed (with or without changes) provided that: + + 1. distributions of this source code include the above copyright + notice, this list of conditions and the following disclaimer; + + 2. distributions in binary form include the above copyright + notice, this list of conditions and the following disclaimer + in the documentation and/or other associated materials; + + 3. the copyright holder's name is not used to endorse products + built using this software without specific written permission. + + ALTERNATIVELY, provided that this notice is retained in full, this product + may be distributed under the terms of the GNU General Public License (GPL), + in which case the provisions of the GPL apply INSTEAD OF those given above. + + DISCLAIMER + + This software is provided 'as is' with no explicit or implied warranties + in respect of its properties, including, but not limited to, correctness + and/or fitness for purpose. + --------------------------------------------------------------------------- + Issue 28/01/2004 + + This file contains the definitions required to use AES in C. See aesopt.h + for optimisation details. +*/ + +#if !defined( _AES_H ) +#define _AES_H + +/* This include is used to find 8 & 32 bit unsigned integer types */ +#include <machine/limits.h> + +#if defined(__cplusplus) +extern "C" +{ +#endif + +#define AES_128 /* define if AES with 128 bit keys is needed */ +#define AES_192 /* define if AES with 192 bit keys is needed */ +#define AES_256 /* define if AES with 256 bit keys is needed */ +#define AES_VAR /* define if a variable key size is needed */ + +/* The following must also be set in assembler files if being used */ + +#define AES_ENCRYPT /* if support for encryption is needed */ +#define AES_DECRYPT /* if support for decryption is needed */ +//#define AES_ERR_CHK /* for parameter checks & error return codes */ + +#if UCHAR_MAX == 0xff /* an unsigned 8 bit type */ + typedef unsigned char aes_08t; +#else +# error Please define aes_08t as an 8-bit unsigned integer type in aes.h +#endif + +#if UINT_MAX == 4294967295 /* an unsigned 32 bit type */ + typedef unsigned int aes_32t; +#elif ULONG_MAX == 4294967295ul + typedef unsigned long aes_32t; +#else +# error Please define aes_32t as a 32-bit unsigned integer type in aes.h +#endif + +#define AES_BLOCK_SIZE 16 /* the AES block size in bytes */ +#define N_COLS 4 /* the number of columns in the state */ + +/* The key schedule length is 11, 13 or 15 16-byte blocks for 128, */ +/* 192 or 256-bit keys respectively. That is 176, 208 or 240 bytes */ +/* or 44, 52 or 60 32-bit words. For simplicity this code allocates */ +/* the maximum 60 word array for the key schedule for all key sizes */ + +#if defined( AES_VAR ) || defined( AES_256 ) +#define KS_LENGTH 60 +#elif defined( AES_192 ) +#define KS_LENGTH 52 +#else +#define KS_LENGTH 44 +#endif + +#if defined( AES_ERR_CHK ) +#define aes_ret int +#define aes_good 0 +#define aes_error -1 +#else +#define aes_ret void +#endif + +#if !defined( AES_DLL ) /* implement normal/DLL functions */ +#define aes_rval aes_ret +#else +#define aes_rval aes_ret __declspec(dllexport) _stdcall +#endif + +typedef struct +{ aes_32t ks[KS_LENGTH]; + aes_32t rn; +} aes_encrypt_ctx; + +typedef struct +{ aes_32t ks[KS_LENGTH]; + aes_32t rn; +} aes_decrypt_ctx; + +typedef struct +{ + aes_decrypt_ctx decrypt; + aes_encrypt_ctx encrypt; +} aes_ctx; + + +/* This routine must be called before first use if non-static */ +/* tables are being used */ + +void gen_tabs(void); + +/* The key length (klen) is input in bytes when it is in the range */ +/* 16 <= klen <= 32 or in bits when in the range 128 <= klen <= 256 */ + +#if defined( AES_ENCRYPT ) + +#if defined(AES_128) || defined(AES_VAR) +aes_rval aes_encrypt_key128(const unsigned char *in_key, aes_encrypt_ctx cx[1]); +#endif + +#if defined(AES_192) || defined(AES_VAR) +aes_rval aes_encrypt_key192(const unsigned char *in_key, aes_encrypt_ctx cx[1]); +#endif + +#if defined(AES_256) || defined(AES_VAR) +aes_rval aes_encrypt_key256(const unsigned char *in_key, aes_encrypt_ctx cx[1]); +#endif + +#if defined(AES_VAR) +aes_rval aes_encrypt_key(const unsigned char *in_key, int key_len, aes_encrypt_ctx cx[1]); +#endif + +aes_rval aes_encrypt_cbc(const unsigned char *in_blk, const unsigned char *in_iv, unsigned int num_blk, + unsigned char *out_blk, const aes_encrypt_ctx cx[1]); +#endif + +#if defined( AES_DECRYPT ) + +#if defined(AES_128) || defined(AES_VAR) +aes_rval aes_decrypt_key128(const unsigned char *in_key, aes_decrypt_ctx cx[1]); +#endif + +#if defined(AES_192) || defined(AES_VAR) +aes_rval aes_decrypt_key192(const unsigned char *in_key, aes_decrypt_ctx cx[1]); +#endif + +#if defined(AES_256) || defined(AES_VAR) +aes_rval aes_decrypt_key256(const unsigned char *in_key, aes_decrypt_ctx cx[1]); +#endif + +#if defined(AES_VAR) +aes_rval aes_decrypt_key(const unsigned char *in_key, int key_len, aes_decrypt_ctx cx[1]); +#endif + +aes_rval aes_decrypt_cbc(const unsigned char *in_blk, const unsigned char *in_iv, unsigned int num_blk, + unsigned char *out_blk, const aes_decrypt_ctx cx[1]); +#endif + +#if defined(__cplusplus) +} +#endif + +#endif diff --git a/bsd/crypto/aes/aescrypt.c b/bsd/crypto/aes/aescrypt.c index f23e9131c..31d4c81af 100644 --- a/bsd/crypto/aes/aescrypt.c +++ b/bsd/crypto/aes/aescrypt.c @@ -1,411 +1,411 @@ -/* - --------------------------------------------------------------------------- - Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. - - LICENSE TERMS - - The free distribution and use of this software in both source and binary - form is allowed (with or without changes) provided that: - - 1. distributions of this source code include the above copyright - notice, this list of conditions and the following disclaimer; - - 2. distributions in binary form include the above copyright - notice, this list of conditions and the following disclaimer - in the documentation and/or other associated materials; - - 3. the copyright holder's name is not used to endorse products - built using this software without specific written permission. - - ALTERNATIVELY, provided that this notice is retained in full, this product - may be distributed under the terms of the GNU General Public License (GPL), - in which case the provisions of the GPL apply INSTEAD OF those given above. - - DISCLAIMER - - This software is provided 'as is' with no explicit or implied warranties - in respect of its properties, including, but not limited to, correctness - and/or fitness for purpose. - --------------------------------------------------------------------------- - Issue 28/01/2004 - - This file contains the code for implementing encryption and decryption - for AES (Rijndael) for block and key sizes of 16, 24 and 32 bytes. It - can optionally be replaced by code written in assembler using NASM. For - further details see the file aesopt.h -*/ - -#include "aesopt.h" -#include "aestab.h" - -#if defined(__cplusplus) -extern "C" -{ -#endif - -#define ki(y,x,k,c) (s(y,c) = s(x, c) ^ (k)[c]) -#define xo(y,x,c) (s(y,c) ^= s(x, c)) -#define si(y,x,c) (s(y,c) = word_in(x, c)) -#define so(y,x,c) word_out(y, c, s(x,c)) - -#if defined(ARRAYS) -#define locals(y,x) x[4],y[4] -#else -#define locals(y,x) x##0,x##1,x##2,x##3,y##0,y##1,y##2,y##3 -#endif - -#define dtables(tab) const aes_32t *tab##0, *tab##1, *tab##2, *tab##3 -#define itables(tab) tab##0 = tab[0]; tab##1 = tab[1]; tab##2 = tab[2]; tab##3 = tab[3] - -#define l_copy(y, x) s(y,0) = s(x,0); s(y,1) = s(x,1); \ - s(y,2) = s(x,2); s(y,3) = s(x,3); - -#define key_in(y,x,k) ki(y,x,k,0); ki(y,x,k,1); ki(y,x,k,2); ki(y,x,k,3) -#define cbc(y,x) xo(y,x,0); xo(y,x,1); xo(y,x,2); xo(y,x,3) -#define state_in(y,x) si(y,x,0); si(y,x,1); si(y,x,2); si(y,x,3) -#define state_out(y,x) so(y,x,0); so(y,x,1); so(y,x,2); so(y,x,3) -#define round(rm,y,x,k) rm(y,x,k,0); rm(y,x,k,1); rm(y,x,k,2); rm(y,x,k,3) - -#if defined(ENCRYPTION) && !defined(AES_ASM) - -/* Visual C++ .Net v7.1 provides the fastest encryption code when using - Pentium optimiation with small code but this is poor for decryption - so we need to control this with the following VC++ pragmas -*/ - -#if defined(_MSC_VER) -#pragma optimize( "s", on ) -#endif - -/* Given the column (c) of the output state variable, the following - macros give the input state variables which are needed in its - computation for each row (r) of the state. All the alternative - macros give the same end values but expand into different ways - of calculating these values. In particular the complex macro - used for dynamically variable block sizes is designed to expand - to a compile time constant whenever possible but will expand to - conditional clauses on some branches (I am grateful to Frank - Yellin for this construction) -*/ - -#define fwd_var(x,r,c)\ - ( r == 0 ? ( c == 0 ? s(x,0) : c == 1 ? s(x,1) : c == 2 ? s(x,2) : s(x,3))\ - : r == 1 ? ( c == 0 ? s(x,1) : c == 1 ? s(x,2) : c == 2 ? s(x,3) : s(x,0))\ - : r == 2 ? ( c == 0 ? s(x,2) : c == 1 ? s(x,3) : c == 2 ? s(x,0) : s(x,1))\ - : ( c == 0 ? s(x,3) : c == 1 ? s(x,0) : c == 2 ? s(x,1) : s(x,2))) - -#if defined(FT4_SET) -#undef dec_fmvars -# if defined(ENC_ROUND_CACHE_TABLES) -#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_fn,fwd_var,rf1,c)) -# else -#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_fn,fwd_var,rf1,c)) -# endif -#elif defined(FT1_SET) -#undef dec_fmvars -#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,upr,t_fn,fwd_var,rf1,c)) -#else -#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ fwd_mcol(no_table(x,t_sbox,fwd_var,rf1,c))) -#endif - -#if defined(FL4_SET) -# if defined(LAST_ENC_ROUND_CACHE_TABLES) -#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_fl,fwd_var,rf1,c)) -# else -#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_fl,fwd_var,rf1,c)) -# endif -#elif defined(FL1_SET) -#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,ups,t_fl,fwd_var,rf1,c)) -#else -#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ no_table(x,t_sbox,fwd_var,rf1,c)) -#endif - -aes_rval aes_encrypt_cbc(const unsigned char *in, const unsigned char *in_iv, unsigned int num_blk, - unsigned char *out, const aes_encrypt_ctx cx[1]) -{ aes_32t locals(b0, b1); - const aes_32t *kp; - const aes_32t *kptr = cx->ks; -#if defined(ENC_ROUND_CACHE_TABLES) - dtables(t_fn); -#endif -#if defined(LAST_ENC_ROUND_CACHE_TABLES) - dtables(t_fl); -#endif - -#if defined( dec_fmvars ) - dec_fmvars; /* declare variables for fwd_mcol() if needed */ -#endif - -#if defined( AES_ERR_CHK ) - if( cx->rn != 10 && cx->rn != 12 && cx->rn != 14 ) - return aes_error; -#endif - - // Load IV into b0. - state_in(b0, in_iv); - - for (;num_blk; in += AES_BLOCK_SIZE, out += AES_BLOCK_SIZE, --num_blk) - { - kp = kptr; -#if 0 - // Read the plaintext into b1 - state_in(b1, in); - // Do the CBC with b0 which is either the iv or the ciphertext of the previous block. - cbc(b1, b0); - - // Xor b1 with the key schedule to get things started. - key_in(b0, b1, kp); -#else - // Since xor is associative we mess with the ordering here to get the loads started early - key_in(b1, b0, kp); // Xor b0(IV) with the key schedule and assign to b1 - state_in(b0, in); // Load block into b0 - cbc(b0, b1); // Xor b0 with b1 and store in b0 -#endif - -#if defined(ENC_ROUND_CACHE_TABLES) - itables(t_fn); -#endif - -#if (ENC_UNROLL == FULL) - - switch(cx->rn) - { - case 14: - round(fwd_rnd, b1, b0, kp + 1 * N_COLS); - round(fwd_rnd, b0, b1, kp + 2 * N_COLS); - kp += 2 * N_COLS; - case 12: - round(fwd_rnd, b1, b0, kp + 1 * N_COLS); - round(fwd_rnd, b0, b1, kp + 2 * N_COLS); - kp += 2 * N_COLS; - case 10: - default: - round(fwd_rnd, b1, b0, kp + 1 * N_COLS); - round(fwd_rnd, b0, b1, kp + 2 * N_COLS); - round(fwd_rnd, b1, b0, kp + 3 * N_COLS); - round(fwd_rnd, b0, b1, kp + 4 * N_COLS); - round(fwd_rnd, b1, b0, kp + 5 * N_COLS); - round(fwd_rnd, b0, b1, kp + 6 * N_COLS); - round(fwd_rnd, b1, b0, kp + 7 * N_COLS); - round(fwd_rnd, b0, b1, kp + 8 * N_COLS); - round(fwd_rnd, b1, b0, kp + 9 * N_COLS); -#if defined(LAST_ENC_ROUND_CACHE_TABLES) - itables(t_fl); -#endif - round(fwd_lrnd, b0, b1, kp +10 * N_COLS); - } - -#else - - { aes_32t rnd; -#if (ENC_UNROLL == PARTIAL) - for(rnd = 0; rnd < (cx->rn >> 1) - 1; ++rnd) - { - kp += N_COLS; - round(fwd_rnd, b1, b0, kp); - kp += N_COLS; - round(fwd_rnd, b0, b1, kp); - } - kp += N_COLS; - round(fwd_rnd, b1, b0, kp); -#else - for(rnd = 0; rnd < cx->rn - 1; ++rnd) - { - kp += N_COLS; - round(fwd_rnd, b1, b0, kp); - l_copy(b0, b1); - } -#endif -#if defined(LAST_ENC_ROUND_CACHE_TABLES) - itables(t_fl); -#endif - kp += N_COLS; - round(fwd_lrnd, b0, b1, kp); - } -#endif - - state_out(out, b0); - } - -#if defined( AES_ERR_CHK ) - return aes_good; -#endif -} - -#endif - -#if defined(DECRYPTION) && !defined(AES_ASM) - -/* Visual C++ .Net v7.1 provides the fastest encryption code when using - Pentium optimiation with small code but this is poor for decryption - so we need to control this with the following VC++ pragmas -*/ - -#if defined(_MSC_VER) -#pragma optimize( "t", on ) -#endif - -/* Given the column (c) of the output state variable, the following - macros give the input state variables which are needed in its - computation for each row (r) of the state. All the alternative - macros give the same end values but expand into different ways - of calculating these values. In particular the complex macro - used for dynamically variable block sizes is designed to expand - to a compile time constant whenever possible but will expand to - conditional clauses on some branches (I am grateful to Frank - Yellin for this construction) -*/ - -#define inv_var(x,r,c)\ - ( r == 0 ? ( c == 0 ? s(x,0) : c == 1 ? s(x,1) : c == 2 ? s(x,2) : s(x,3))\ - : r == 1 ? ( c == 0 ? s(x,3) : c == 1 ? s(x,0) : c == 2 ? s(x,1) : s(x,2))\ - : r == 2 ? ( c == 0 ? s(x,2) : c == 1 ? s(x,3) : c == 2 ? s(x,0) : s(x,1))\ - : ( c == 0 ? s(x,1) : c == 1 ? s(x,2) : c == 2 ? s(x,3) : s(x,0))) - -#if defined(IT4_SET) -#undef dec_imvars -# if defined(DEC_ROUND_CACHE_TABLES) -#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_in,inv_var,rf1,c)) -# else -#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_in,inv_var,rf1,c)) -# endif -#elif defined(IT1_SET) -#undef dec_imvars -#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,upr,t_in,inv_var,rf1,c)) -#else -#define inv_rnd(y,x,k,c) (s(y,c) = inv_mcol((k)[c] ^ no_table(x,t_ibox,inv_var,rf1,c))) -#endif - -#if defined(IL4_SET) -# if defined(LAST_DEC_ROUND_CACHE_TABLES) -#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_il,inv_var,rf1,c)) -# else -#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_il,inv_var,rf1,c)) -# endif -#elif defined(IL1_SET) -#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,ups,t_il,inv_var,rf1,c)) -#else -#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ no_table(x,t_ibox,inv_var,rf1,c)) -#endif - -aes_rval aes_decrypt_cbc(const unsigned char *in, const unsigned char *in_iv, unsigned int num_blk, - unsigned char *out, const aes_decrypt_ctx cx[1]) -{ aes_32t locals(b0, b1); - const aes_32t *kptr = cx->ks + cx->rn * N_COLS; - const aes_32t *kp; -#if defined(DEC_ROUND_CACHE_TABLES) - dtables(t_in); -#endif -#if defined(LAST_DEC_ROUND_CACHE_TABLES) - dtables(t_il); -#endif - -#if defined( dec_imvars ) - dec_imvars; /* declare variables for inv_mcol() if needed */ -#endif - -#if defined( AES_ERR_CHK ) - if( cx->rn != 10 && cx->rn != 12 && cx->rn != 14 ) - return aes_error; -#endif - -#if defined(DEC_ROUND_CACHE_TABLES) - itables(t_in); -#endif - - in += AES_BLOCK_SIZE * (num_blk - 1); - out += AES_BLOCK_SIZE * (num_blk - 1); - // Load the last block's ciphertext into b1 - state_in(b1, in); - - for (;num_blk; out -= AES_BLOCK_SIZE, --num_blk) - { - kp = kptr; - // Do the xor part of state_in, where b1 is the previous block's ciphertext. - key_in(b0, b1, kp); - -#if (DEC_UNROLL == FULL) - - switch(cx->rn) - { - case 14: - round(inv_rnd, b1, b0, kp - 1 * N_COLS); - round(inv_rnd, b0, b1, kp - 2 * N_COLS); - kp -= 2 * N_COLS; - case 12: - round(inv_rnd, b1, b0, kp - 1 * N_COLS); - round(inv_rnd, b0, b1, kp - 2 * N_COLS); - kp -= 2 * N_COLS; - case 10: - default: - round(inv_rnd, b1, b0, kp - 1 * N_COLS); - round(inv_rnd, b0, b1, kp - 2 * N_COLS); - round(inv_rnd, b1, b0, kp - 3 * N_COLS); - round(inv_rnd, b0, b1, kp - 4 * N_COLS); - round(inv_rnd, b1, b0, kp - 5 * N_COLS); - round(inv_rnd, b0, b1, kp - 6 * N_COLS); - round(inv_rnd, b1, b0, kp - 7 * N_COLS); - round(inv_rnd, b0, b1, kp - 8 * N_COLS); - round(inv_rnd, b1, b0, kp - 9 * N_COLS); -#if defined(LAST_DEC_ROUND_CACHE_TABLES) - itables(t_il); -#endif - round(inv_lrnd, b0, b1, kp - 10 * N_COLS); - } - -#else - - { aes_32t rnd; -#if (DEC_UNROLL == PARTIAL) - for(rnd = 0; rnd < (cx->rn >> 1) - 1; ++rnd) - { - kp -= N_COLS; - round(inv_rnd, b1, b0, kp); - kp -= N_COLS; - round(inv_rnd, b0, b1, kp); - } - kp -= N_COLS; - round(inv_rnd, b1, b0, kp); -#else - for(rnd = 0; rnd < cx->rn - 1; ++rnd) - { - kp -= N_COLS; - round(inv_rnd, b1, b0, kp); - l_copy(b0, b1); - } -#endif -#if defined(LAST_DEC_ROUND_CACHE_TABLES) - itables(t_il); -#endif - kp -= N_COLS; - round(inv_lrnd, b0, b1, kp); - } -#endif - - if (num_blk == 1) - { - // We are doing the first block so we need the IV rather than the previous - // block for CBC (there is no previous block) - state_in(b1, in_iv); - } - else - { - in -= AES_BLOCK_SIZE; - state_in(b1, in); - } - - // Do the CBC with b1 which is either the IV or the ciphertext of the previous block. - cbc(b0, b1); - - state_out(out, b0); - } -#if defined( AES_ERR_CHK ) - return aes_good; -#endif -} - -#endif - -#if defined(__cplusplus) -} -#endif +/* + --------------------------------------------------------------------------- + Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. + + LICENSE TERMS + + The free distribution and use of this software in both source and binary + form is allowed (with or without changes) provided that: + + 1. distributions of this source code include the above copyright + notice, this list of conditions and the following disclaimer; + + 2. distributions in binary form include the above copyright + notice, this list of conditions and the following disclaimer + in the documentation and/or other associated materials; + + 3. the copyright holder's name is not used to endorse products + built using this software without specific written permission. + + ALTERNATIVELY, provided that this notice is retained in full, this product + may be distributed under the terms of the GNU General Public License (GPL), + in which case the provisions of the GPL apply INSTEAD OF those given above. + + DISCLAIMER + + This software is provided 'as is' with no explicit or implied warranties + in respect of its properties, including, but not limited to, correctness + and/or fitness for purpose. + --------------------------------------------------------------------------- + Issue 28/01/2004 + + This file contains the code for implementing encryption and decryption + for AES (Rijndael) for block and key sizes of 16, 24 and 32 bytes. It + can optionally be replaced by code written in assembler using NASM. For + further details see the file aesopt.h +*/ + +#include "aesopt.h" +#include "aestab.h" + +#if defined(__cplusplus) +extern "C" +{ +#endif + +#define ki(y,x,k,c) (s(y,c) = s(x, c) ^ (k)[c]) +#define xo(y,x,c) (s(y,c) ^= s(x, c)) +#define si(y,x,c) (s(y,c) = word_in(x, c)) +#define so(y,x,c) word_out(y, c, s(x,c)) + +#if defined(ARRAYS) +#define locals(y,x) x[4],y[4] +#else +#define locals(y,x) x##0,x##1,x##2,x##3,y##0,y##1,y##2,y##3 +#endif + +#define dtables(tab) const aes_32t *tab##0, *tab##1, *tab##2, *tab##3 +#define itables(tab) tab##0 = tab[0]; tab##1 = tab[1]; tab##2 = tab[2]; tab##3 = tab[3] + +#define l_copy(y, x) s(y,0) = s(x,0); s(y,1) = s(x,1); \ + s(y,2) = s(x,2); s(y,3) = s(x,3); + +#define key_in(y,x,k) ki(y,x,k,0); ki(y,x,k,1); ki(y,x,k,2); ki(y,x,k,3) +#define cbc(y,x) xo(y,x,0); xo(y,x,1); xo(y,x,2); xo(y,x,3) +#define state_in(y,x) si(y,x,0); si(y,x,1); si(y,x,2); si(y,x,3) +#define state_out(y,x) so(y,x,0); so(y,x,1); so(y,x,2); so(y,x,3) +#define round(rm,y,x,k) rm(y,x,k,0); rm(y,x,k,1); rm(y,x,k,2); rm(y,x,k,3) + +#if defined(ENCRYPTION) && !defined(AES_ASM) + +/* Visual C++ .Net v7.1 provides the fastest encryption code when using + Pentium optimiation with small code but this is poor for decryption + so we need to control this with the following VC++ pragmas +*/ + +#if defined(_MSC_VER) +#pragma optimize( "s", on ) +#endif + +/* Given the column (c) of the output state variable, the following + macros give the input state variables which are needed in its + computation for each row (r) of the state. All the alternative + macros give the same end values but expand into different ways + of calculating these values. In particular the complex macro + used for dynamically variable block sizes is designed to expand + to a compile time constant whenever possible but will expand to + conditional clauses on some branches (I am grateful to Frank + Yellin for this construction) +*/ + +#define fwd_var(x,r,c)\ + ( r == 0 ? ( c == 0 ? s(x,0) : c == 1 ? s(x,1) : c == 2 ? s(x,2) : s(x,3))\ + : r == 1 ? ( c == 0 ? s(x,1) : c == 1 ? s(x,2) : c == 2 ? s(x,3) : s(x,0))\ + : r == 2 ? ( c == 0 ? s(x,2) : c == 1 ? s(x,3) : c == 2 ? s(x,0) : s(x,1))\ + : ( c == 0 ? s(x,3) : c == 1 ? s(x,0) : c == 2 ? s(x,1) : s(x,2))) + +#if defined(FT4_SET) +#undef dec_fmvars +# if defined(ENC_ROUND_CACHE_TABLES) +#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_fn,fwd_var,rf1,c)) +# else +#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_fn,fwd_var,rf1,c)) +# endif +#elif defined(FT1_SET) +#undef dec_fmvars +#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,upr,t_fn,fwd_var,rf1,c)) +#else +#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ fwd_mcol(no_table(x,t_sbox,fwd_var,rf1,c))) +#endif + +#if defined(FL4_SET) +# if defined(LAST_ENC_ROUND_CACHE_TABLES) +#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_fl,fwd_var,rf1,c)) +# else +#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_fl,fwd_var,rf1,c)) +# endif +#elif defined(FL1_SET) +#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,ups,t_fl,fwd_var,rf1,c)) +#else +#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ no_table(x,t_sbox,fwd_var,rf1,c)) +#endif + +aes_rval aes_encrypt_cbc(const unsigned char *in, const unsigned char *in_iv, unsigned int num_blk, + unsigned char *out, const aes_encrypt_ctx cx[1]) +{ aes_32t locals(b0, b1); + const aes_32t *kp; + const aes_32t *kptr = cx->ks; +#if defined(ENC_ROUND_CACHE_TABLES) + dtables(t_fn); +#endif +#if defined(LAST_ENC_ROUND_CACHE_TABLES) + dtables(t_fl); +#endif + +#if defined( dec_fmvars ) + dec_fmvars; /* declare variables for fwd_mcol() if needed */ +#endif + +#if defined( AES_ERR_CHK ) + if( cx->rn != 10 && cx->rn != 12 && cx->rn != 14 ) + return aes_error; +#endif + + // Load IV into b0. + state_in(b0, in_iv); + + for (;num_blk; in += AES_BLOCK_SIZE, out += AES_BLOCK_SIZE, --num_blk) + { + kp = kptr; +#if 0 + // Read the plaintext into b1 + state_in(b1, in); + // Do the CBC with b0 which is either the iv or the ciphertext of the previous block. + cbc(b1, b0); + + // Xor b1 with the key schedule to get things started. + key_in(b0, b1, kp); +#else + // Since xor is associative we mess with the ordering here to get the loads started early + key_in(b1, b0, kp); // Xor b0(IV) with the key schedule and assign to b1 + state_in(b0, in); // Load block into b0 + cbc(b0, b1); // Xor b0 with b1 and store in b0 +#endif + +#if defined(ENC_ROUND_CACHE_TABLES) + itables(t_fn); +#endif + +#if (ENC_UNROLL == FULL) + + switch(cx->rn) + { + case 14: + round(fwd_rnd, b1, b0, kp + 1 * N_COLS); + round(fwd_rnd, b0, b1, kp + 2 * N_COLS); + kp += 2 * N_COLS; + case 12: + round(fwd_rnd, b1, b0, kp + 1 * N_COLS); + round(fwd_rnd, b0, b1, kp + 2 * N_COLS); + kp += 2 * N_COLS; + case 10: + default: + round(fwd_rnd, b1, b0, kp + 1 * N_COLS); + round(fwd_rnd, b0, b1, kp + 2 * N_COLS); + round(fwd_rnd, b1, b0, kp + 3 * N_COLS); + round(fwd_rnd, b0, b1, kp + 4 * N_COLS); + round(fwd_rnd, b1, b0, kp + 5 * N_COLS); + round(fwd_rnd, b0, b1, kp + 6 * N_COLS); + round(fwd_rnd, b1, b0, kp + 7 * N_COLS); + round(fwd_rnd, b0, b1, kp + 8 * N_COLS); + round(fwd_rnd, b1, b0, kp + 9 * N_COLS); +#if defined(LAST_ENC_ROUND_CACHE_TABLES) + itables(t_fl); +#endif + round(fwd_lrnd, b0, b1, kp +10 * N_COLS); + } + +#else + + { aes_32t rnd; +#if (ENC_UNROLL == PARTIAL) + for(rnd = 0; rnd < (cx->rn >> 1) - 1; ++rnd) + { + kp += N_COLS; + round(fwd_rnd, b1, b0, kp); + kp += N_COLS; + round(fwd_rnd, b0, b1, kp); + } + kp += N_COLS; + round(fwd_rnd, b1, b0, kp); +#else + for(rnd = 0; rnd < cx->rn - 1; ++rnd) + { + kp += N_COLS; + round(fwd_rnd, b1, b0, kp); + l_copy(b0, b1); + } +#endif +#if defined(LAST_ENC_ROUND_CACHE_TABLES) + itables(t_fl); +#endif + kp += N_COLS; + round(fwd_lrnd, b0, b1, kp); + } +#endif + + state_out(out, b0); + } + +#if defined( AES_ERR_CHK ) + return aes_good; +#endif +} + +#endif + +#if defined(DECRYPTION) && !defined(AES_ASM) + +/* Visual C++ .Net v7.1 provides the fastest encryption code when using + Pentium optimiation with small code but this is poor for decryption + so we need to control this with the following VC++ pragmas +*/ + +#if defined(_MSC_VER) +#pragma optimize( "t", on ) +#endif + +/* Given the column (c) of the output state variable, the following + macros give the input state variables which are needed in its + computation for each row (r) of the state. All the alternative + macros give the same end values but expand into different ways + of calculating these values. In particular the complex macro + used for dynamically variable block sizes is designed to expand + to a compile time constant whenever possible but will expand to + conditional clauses on some branches (I am grateful to Frank + Yellin for this construction) +*/ + +#define inv_var(x,r,c)\ + ( r == 0 ? ( c == 0 ? s(x,0) : c == 1 ? s(x,1) : c == 2 ? s(x,2) : s(x,3))\ + : r == 1 ? ( c == 0 ? s(x,3) : c == 1 ? s(x,0) : c == 2 ? s(x,1) : s(x,2))\ + : r == 2 ? ( c == 0 ? s(x,2) : c == 1 ? s(x,3) : c == 2 ? s(x,0) : s(x,1))\ + : ( c == 0 ? s(x,1) : c == 1 ? s(x,2) : c == 2 ? s(x,3) : s(x,0))) + +#if defined(IT4_SET) +#undef dec_imvars +# if defined(DEC_ROUND_CACHE_TABLES) +#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_in,inv_var,rf1,c)) +# else +#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_in,inv_var,rf1,c)) +# endif +#elif defined(IT1_SET) +#undef dec_imvars +#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,upr,t_in,inv_var,rf1,c)) +#else +#define inv_rnd(y,x,k,c) (s(y,c) = inv_mcol((k)[c] ^ no_table(x,t_ibox,inv_var,rf1,c))) +#endif + +#if defined(IL4_SET) +# if defined(LAST_DEC_ROUND_CACHE_TABLES) +#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_il,inv_var,rf1,c)) +# else +#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_il,inv_var,rf1,c)) +# endif +#elif defined(IL1_SET) +#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,ups,t_il,inv_var,rf1,c)) +#else +#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ no_table(x,t_ibox,inv_var,rf1,c)) +#endif + +aes_rval aes_decrypt_cbc(const unsigned char *in, const unsigned char *in_iv, unsigned int num_blk, + unsigned char *out, const aes_decrypt_ctx cx[1]) +{ aes_32t locals(b0, b1); + const aes_32t *kptr = cx->ks + cx->rn * N_COLS; + const aes_32t *kp; +#if defined(DEC_ROUND_CACHE_TABLES) + dtables(t_in); +#endif +#if defined(LAST_DEC_ROUND_CACHE_TABLES) + dtables(t_il); +#endif + +#if defined( dec_imvars ) + dec_imvars; /* declare variables for inv_mcol() if needed */ +#endif + +#if defined( AES_ERR_CHK ) + if( cx->rn != 10 && cx->rn != 12 && cx->rn != 14 ) + return aes_error; +#endif + +#if defined(DEC_ROUND_CACHE_TABLES) + itables(t_in); +#endif + + in += AES_BLOCK_SIZE * (num_blk - 1); + out += AES_BLOCK_SIZE * (num_blk - 1); + // Load the last block's ciphertext into b1 + state_in(b1, in); + + for (;num_blk; out -= AES_BLOCK_SIZE, --num_blk) + { + kp = kptr; + // Do the xor part of state_in, where b1 is the previous block's ciphertext. + key_in(b0, b1, kp); + +#if (DEC_UNROLL == FULL) + + switch(cx->rn) + { + case 14: + round(inv_rnd, b1, b0, kp - 1 * N_COLS); + round(inv_rnd, b0, b1, kp - 2 * N_COLS); + kp -= 2 * N_COLS; + case 12: + round(inv_rnd, b1, b0, kp - 1 * N_COLS); + round(inv_rnd, b0, b1, kp - 2 * N_COLS); + kp -= 2 * N_COLS; + case 10: + default: + round(inv_rnd, b1, b0, kp - 1 * N_COLS); + round(inv_rnd, b0, b1, kp - 2 * N_COLS); + round(inv_rnd, b1, b0, kp - 3 * N_COLS); + round(inv_rnd, b0, b1, kp - 4 * N_COLS); + round(inv_rnd, b1, b0, kp - 5 * N_COLS); + round(inv_rnd, b0, b1, kp - 6 * N_COLS); + round(inv_rnd, b1, b0, kp - 7 * N_COLS); + round(inv_rnd, b0, b1, kp - 8 * N_COLS); + round(inv_rnd, b1, b0, kp - 9 * N_COLS); +#if defined(LAST_DEC_ROUND_CACHE_TABLES) + itables(t_il); +#endif + round(inv_lrnd, b0, b1, kp - 10 * N_COLS); + } + +#else + + { aes_32t rnd; +#if (DEC_UNROLL == PARTIAL) + for(rnd = 0; rnd < (cx->rn >> 1) - 1; ++rnd) + { + kp -= N_COLS; + round(inv_rnd, b1, b0, kp); + kp -= N_COLS; + round(inv_rnd, b0, b1, kp); + } + kp -= N_COLS; + round(inv_rnd, b1, b0, kp); +#else + for(rnd = 0; rnd < cx->rn - 1; ++rnd) + { + kp -= N_COLS; + round(inv_rnd, b1, b0, kp); + l_copy(b0, b1); + } +#endif +#if defined(LAST_DEC_ROUND_CACHE_TABLES) + itables(t_il); +#endif + kp -= N_COLS; + round(inv_lrnd, b0, b1, kp); + } +#endif + + if (num_blk == 1) + { + // We are doing the first block so we need the IV rather than the previous + // block for CBC (there is no previous block) + state_in(b1, in_iv); + } + else + { + in -= AES_BLOCK_SIZE; + state_in(b1, in); + } + + // Do the CBC with b1 which is either the IV or the ciphertext of the previous block. + cbc(b0, b1); + + state_out(out, b0); + } +#if defined( AES_ERR_CHK ) + return aes_good; +#endif +} + +#endif + +#if defined(__cplusplus) +} +#endif diff --git a/bsd/crypto/aes/aeskey.c b/bsd/crypto/aes/aeskey.c index 0120e0c7d..5e0a6453c 100644 --- a/bsd/crypto/aes/aeskey.c +++ b/bsd/crypto/aes/aeskey.c @@ -1,455 +1,455 @@ -/* - --------------------------------------------------------------------------- - Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. - - LICENSE TERMS - - The free distribution and use of this software in both source and binary - form is allowed (with or without changes) provided that: - - 1. distributions of this source code include the above copyright - notice, this list of conditions and the following disclaimer; - - 2. distributions in binary form include the above copyright - notice, this list of conditions and the following disclaimer - in the documentation and/or other associated materials; - - 3. the copyright holder's name is not used to endorse products - built using this software without specific written permission. - - ALTERNATIVELY, provided that this notice is retained in full, this product - may be distributed under the terms of the GNU General Public License (GPL), - in which case the provisions of the GPL apply INSTEAD OF those given above. - - DISCLAIMER - - This software is provided 'as is' with no explicit or implied warranties - in respect of its properties, including, but not limited to, correctness - and/or fitness for purpose. - --------------------------------------------------------------------------- - Issue Date: 26/08/2003 - - This file contains the code for implementing the key schedule for AES - (Rijndael) for block and key sizes of 16, 24, and 32 bytes. See aesopt.h - for further details including optimisation. -*/ - -#include "aesopt.h" -#include "aestab.h" - -#if defined(__cplusplus) -extern "C" -{ -#endif - -/* Initialise the key schedule from the user supplied key. The key - length can be specified in bytes, with legal values of 16, 24 - and 32, or in bits, with legal values of 128, 192 and 256. These - values correspond with Nk values of 4, 6 and 8 respectively. - - The following macros implement a single cycle in the key - schedule generation process. The number of cycles needed - for each cx->n_col and nk value is: - - nk = 4 5 6 7 8 - ------------------------------ - cx->n_col = 4 10 9 8 7 7 - cx->n_col = 5 14 11 10 9 9 - cx->n_col = 6 19 15 12 11 11 - cx->n_col = 7 21 19 16 13 14 - cx->n_col = 8 29 23 19 17 14 -*/ - -#define ke4(k,i) \ -{ k[4*(i)+4] = ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+5] = ss[1] ^= ss[0]; \ - k[4*(i)+6] = ss[2] ^= ss[1]; k[4*(i)+7] = ss[3] ^= ss[2]; \ -} -#define kel4(k,i) \ -{ k[4*(i)+4] = ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+5] = ss[1] ^= ss[0]; \ - k[4*(i)+6] = ss[2] ^= ss[1]; k[4*(i)+7] = ss[3] ^= ss[2]; \ -} - -#define ke6(k,i) \ -{ k[6*(i)+ 6] = ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 7] = ss[1] ^= ss[0]; \ - k[6*(i)+ 8] = ss[2] ^= ss[1]; k[6*(i)+ 9] = ss[3] ^= ss[2]; \ - k[6*(i)+10] = ss[4] ^= ss[3]; k[6*(i)+11] = ss[5] ^= ss[4]; \ -} -#define kel6(k,i) \ -{ k[6*(i)+ 6] = ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 7] = ss[1] ^= ss[0]; \ - k[6*(i)+ 8] = ss[2] ^= ss[1]; k[6*(i)+ 9] = ss[3] ^= ss[2]; \ -} - -#define ke8(k,i) \ -{ k[8*(i)+ 8] = ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 9] = ss[1] ^= ss[0]; \ - k[8*(i)+10] = ss[2] ^= ss[1]; k[8*(i)+11] = ss[3] ^= ss[2]; \ - k[8*(i)+12] = ss[4] ^= ls_box(ss[3],0); k[8*(i)+13] = ss[5] ^= ss[4]; \ - k[8*(i)+14] = ss[6] ^= ss[5]; k[8*(i)+15] = ss[7] ^= ss[6]; \ -} -#define kel8(k,i) \ -{ k[8*(i)+ 8] = ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 9] = ss[1] ^= ss[0]; \ - k[8*(i)+10] = ss[2] ^= ss[1]; k[8*(i)+11] = ss[3] ^= ss[2]; \ -} - -#if defined(ENCRYPTION_KEY_SCHEDULE) - -#if defined(AES_128) || defined(AES_VAR) - -aes_rval aes_encrypt_key128(const unsigned char *key, aes_encrypt_ctx cx[1]) -{ aes_32t ss[4]; - - cx->ks[0] = ss[0] = word_in(key, 0); - cx->ks[1] = ss[1] = word_in(key, 1); - cx->ks[2] = ss[2] = word_in(key, 2); - cx->ks[3] = ss[3] = word_in(key, 3); - -#if ENC_UNROLL == NONE - { aes_32t i; - - for(i = 0; i < ((11 * N_COLS - 5) / 4); ++i) - ke4(cx->ks, i); - } -#else - ke4(cx->ks, 0); ke4(cx->ks, 1); - ke4(cx->ks, 2); ke4(cx->ks, 3); - ke4(cx->ks, 4); ke4(cx->ks, 5); - ke4(cx->ks, 6); ke4(cx->ks, 7); - ke4(cx->ks, 8); -#endif - kel4(cx->ks, 9); - cx->rn = 10; -#if defined( AES_ERR_CHK ) - return aes_good; -#endif -} - -#endif - -#if defined(AES_192) || defined(AES_VAR) - -aes_rval aes_encrypt_key192(const unsigned char *key, aes_encrypt_ctx cx[1]) -{ aes_32t ss[6]; - - cx->ks[0] = ss[0] = word_in(key, 0); - cx->ks[1] = ss[1] = word_in(key, 1); - cx->ks[2] = ss[2] = word_in(key, 2); - cx->ks[3] = ss[3] = word_in(key, 3); - cx->ks[4] = ss[4] = word_in(key, 4); - cx->ks[5] = ss[5] = word_in(key, 5); - -#if ENC_UNROLL == NONE - { aes_32t i; - - for(i = 0; i < (13 * N_COLS - 7) / 6; ++i) - ke6(cx->ks, i); - } -#else - ke6(cx->ks, 0); ke6(cx->ks, 1); - ke6(cx->ks, 2); ke6(cx->ks, 3); - ke6(cx->ks, 4); ke6(cx->ks, 5); - ke6(cx->ks, 6); -#endif - kel6(cx->ks, 7); - cx->rn = 12; -#if defined( AES_ERR_CHK ) - return aes_good; -#endif -} - -#endif - -#if defined(AES_256) || defined(AES_VAR) - -aes_rval aes_encrypt_key256(const unsigned char *key, aes_encrypt_ctx cx[1]) -{ aes_32t ss[8]; - - cx->ks[0] = ss[0] = word_in(key, 0); - cx->ks[1] = ss[1] = word_in(key, 1); - cx->ks[2] = ss[2] = word_in(key, 2); - cx->ks[3] = ss[3] = word_in(key, 3); - cx->ks[4] = ss[4] = word_in(key, 4); - cx->ks[5] = ss[5] = word_in(key, 5); - cx->ks[6] = ss[6] = word_in(key, 6); - cx->ks[7] = ss[7] = word_in(key, 7); - -#if ENC_UNROLL == NONE - { aes_32t i; - - for(i = 0; i < (15 * N_COLS - 9) / 8; ++i) - ke8(cx->ks, i); - } -#else - ke8(cx->ks, 0); ke8(cx->ks, 1); - ke8(cx->ks, 2); ke8(cx->ks, 3); - ke8(cx->ks, 4); ke8(cx->ks, 5); -#endif - kel8(cx->ks, 6); - cx->rn = 14; -#if defined( AES_ERR_CHK ) - return aes_good; -#endif -} - -#endif - -#if defined(AES_VAR) - -aes_rval aes_encrypt_key(const unsigned char *key, int key_len, aes_encrypt_ctx cx[1]) -{ - switch(key_len) - { -#if defined( AES_ERR_CHK ) - case 16: case 128: return aes_encrypt_key128(key, cx); - case 24: case 192: return aes_encrypt_key192(key, cx); - case 32: case 256: return aes_encrypt_key256(key, cx); - default: return aes_error; -#else - case 16: case 128: aes_encrypt_key128(key, cx); return; - case 24: case 192: aes_encrypt_key192(key, cx); return; - case 32: case 256: aes_encrypt_key256(key, cx); return; -#endif - } -} - -#endif - -#endif - -#if defined(DECRYPTION_KEY_SCHEDULE) - -#if DEC_ROUND == NO_TABLES -#define ff(x) (x) -#else -#define ff(x) inv_mcol(x) -#if defined( dec_imvars ) -#define d_vars dec_imvars -#endif -#endif - -#if 1 -#define kdf4(k,i) \ -{ ss[0] = ss[0] ^ ss[2] ^ ss[1] ^ ss[3]; ss[1] = ss[1] ^ ss[3]; ss[2] = ss[2] ^ ss[3]; ss[3] = ss[3]; \ - ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; \ - ss[4] ^= k[4*(i)]; k[4*(i)+4] = ff(ss[4]); ss[4] ^= k[4*(i)+1]; k[4*(i)+5] = ff(ss[4]); \ - ss[4] ^= k[4*(i)+2]; k[4*(i)+6] = ff(ss[4]); ss[4] ^= k[4*(i)+3]; k[4*(i)+7] = ff(ss[4]); \ -} -#define kd4(k,i) \ -{ ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; ss[4] = ff(ss[4]); \ - k[4*(i)+4] = ss[4] ^= k[4*(i)]; k[4*(i)+5] = ss[4] ^= k[4*(i)+1]; \ - k[4*(i)+6] = ss[4] ^= k[4*(i)+2]; k[4*(i)+7] = ss[4] ^= k[4*(i)+3]; \ -} -#define kdl4(k,i) \ -{ ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; \ - k[4*(i)+4] = (ss[0] ^= ss[1]) ^ ss[2] ^ ss[3]; k[4*(i)+5] = ss[1] ^ ss[3]; \ - k[4*(i)+6] = ss[0]; k[4*(i)+7] = ss[1]; \ -} -#else -#define kdf4(k,i) \ -{ ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+ 4] = ff(ss[0]); ss[1] ^= ss[0]; k[4*(i)+ 5] = ff(ss[1]); \ - ss[2] ^= ss[1]; k[4*(i)+ 6] = ff(ss[2]); ss[3] ^= ss[2]; k[4*(i)+ 7] = ff(ss[3]); \ -} -#define kd4(k,i) \ -{ ss[4] = ls_box(ss[3],3) ^ t_use(r,c)[i]; \ - ss[0] ^= ss[4]; ss[4] = ff(ss[4]); k[4*(i)+ 4] = ss[4] ^= k[4*(i)]; \ - ss[1] ^= ss[0]; k[4*(i)+ 5] = ss[4] ^= k[4*(i)+ 1]; \ - ss[2] ^= ss[1]; k[4*(i)+ 6] = ss[4] ^= k[4*(i)+ 2]; \ - ss[3] ^= ss[2]; k[4*(i)+ 7] = ss[4] ^= k[4*(i)+ 3]; \ -} -#define kdl4(k,i) \ -{ ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+ 4] = ss[0]; ss[1] ^= ss[0]; k[4*(i)+ 5] = ss[1]; \ - ss[2] ^= ss[1]; k[4*(i)+ 6] = ss[2]; ss[3] ^= ss[2]; k[4*(i)+ 7] = ss[3]; \ -} -#endif - -#define kdf6(k,i) \ -{ ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 6] = ff(ss[0]); ss[1] ^= ss[0]; k[6*(i)+ 7] = ff(ss[1]); \ - ss[2] ^= ss[1]; k[6*(i)+ 8] = ff(ss[2]); ss[3] ^= ss[2]; k[6*(i)+ 9] = ff(ss[3]); \ - ss[4] ^= ss[3]; k[6*(i)+10] = ff(ss[4]); ss[5] ^= ss[4]; k[6*(i)+11] = ff(ss[5]); \ -} -#define kd6(k,i) \ -{ ss[6] = ls_box(ss[5],3) ^ t_use(r,c)[i]; \ - ss[0] ^= ss[6]; ss[6] = ff(ss[6]); k[6*(i)+ 6] = ss[6] ^= k[6*(i)]; \ - ss[1] ^= ss[0]; k[6*(i)+ 7] = ss[6] ^= k[6*(i)+ 1]; \ - ss[2] ^= ss[1]; k[6*(i)+ 8] = ss[6] ^= k[6*(i)+ 2]; \ - ss[3] ^= ss[2]; k[6*(i)+ 9] = ss[6] ^= k[6*(i)+ 3]; \ - ss[4] ^= ss[3]; k[6*(i)+10] = ss[6] ^= k[6*(i)+ 4]; \ - ss[5] ^= ss[4]; k[6*(i)+11] = ss[6] ^= k[6*(i)+ 5]; \ -} -#define kdl6(k,i) \ -{ ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 6] = ss[0]; ss[1] ^= ss[0]; k[6*(i)+ 7] = ss[1]; \ - ss[2] ^= ss[1]; k[6*(i)+ 8] = ss[2]; ss[3] ^= ss[2]; k[6*(i)+ 9] = ss[3]; \ -} - -#define kdf8(k,i) \ -{ ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 8] = ff(ss[0]); ss[1] ^= ss[0]; k[8*(i)+ 9] = ff(ss[1]); \ - ss[2] ^= ss[1]; k[8*(i)+10] = ff(ss[2]); ss[3] ^= ss[2]; k[8*(i)+11] = ff(ss[3]); \ - ss[4] ^= ls_box(ss[3],0); k[8*(i)+12] = ff(ss[4]); ss[5] ^= ss[4]; k[8*(i)+13] = ff(ss[5]); \ - ss[6] ^= ss[5]; k[8*(i)+14] = ff(ss[6]); ss[7] ^= ss[6]; k[8*(i)+15] = ff(ss[7]); \ -} -#define kd8(k,i) \ -{ aes_32t g = ls_box(ss[7],3) ^ t_use(r,c)[i]; \ - ss[0] ^= g; g = ff(g); k[8*(i)+ 8] = g ^= k[8*(i)]; \ - ss[1] ^= ss[0]; k[8*(i)+ 9] = g ^= k[8*(i)+ 1]; \ - ss[2] ^= ss[1]; k[8*(i)+10] = g ^= k[8*(i)+ 2]; \ - ss[3] ^= ss[2]; k[8*(i)+11] = g ^= k[8*(i)+ 3]; \ - g = ls_box(ss[3],0); \ - ss[4] ^= g; g = ff(g); k[8*(i)+12] = g ^= k[8*(i)+ 4]; \ - ss[5] ^= ss[4]; k[8*(i)+13] = g ^= k[8*(i)+ 5]; \ - ss[6] ^= ss[5]; k[8*(i)+14] = g ^= k[8*(i)+ 6]; \ - ss[7] ^= ss[6]; k[8*(i)+15] = g ^= k[8*(i)+ 7]; \ -} -#define kdl8(k,i) \ -{ ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 8] = ss[0]; ss[1] ^= ss[0]; k[8*(i)+ 9] = ss[1]; \ - ss[2] ^= ss[1]; k[8*(i)+10] = ss[2]; ss[3] ^= ss[2]; k[8*(i)+11] = ss[3]; \ -} - -#if defined(AES_128) || defined(AES_VAR) - -aes_rval aes_decrypt_key128(const unsigned char *key, aes_decrypt_ctx cx[1]) -{ aes_32t ss[5]; -#if defined( d_vars ) - d_vars; -#endif - cx->ks[0] = ss[0] = word_in(key, 0); - cx->ks[1] = ss[1] = word_in(key, 1); - cx->ks[2] = ss[2] = word_in(key, 2); - cx->ks[3] = ss[3] = word_in(key, 3); - -#if DEC_UNROLL == NONE - { aes_32t i; - - for(i = 0; i < (11 * N_COLS - 5) / 4; ++i) - ke4(cx->ks, i); - kel4(cx->ks, 9); -#if !(DEC_ROUND == NO_TABLES) - for(i = N_COLS; i < 10 * N_COLS; ++i) - cx->ks[i] = inv_mcol(cx->ks[i]); -#endif - } -#else - kdf4(cx->ks, 0); kd4(cx->ks, 1); - kd4(cx->ks, 2); kd4(cx->ks, 3); - kd4(cx->ks, 4); kd4(cx->ks, 5); - kd4(cx->ks, 6); kd4(cx->ks, 7); - kd4(cx->ks, 8); kdl4(cx->ks, 9); -#endif - cx->rn = 10; -#if defined( AES_ERR_CHK ) - return aes_good; -#endif -} - -#endif - -#if defined(AES_192) || defined(AES_VAR) - -aes_rval aes_decrypt_key192(const unsigned char *key, aes_decrypt_ctx cx[1]) -{ aes_32t ss[7]; -#if defined( d_vars ) - d_vars; -#endif - cx->ks[0] = ss[0] = word_in(key, 0); - cx->ks[1] = ss[1] = word_in(key, 1); - cx->ks[2] = ss[2] = word_in(key, 2); - cx->ks[3] = ss[3] = word_in(key, 3); - -#if DEC_UNROLL == NONE - cx->ks[4] = ss[4] = word_in(key, 4); - cx->ks[5] = ss[5] = word_in(key, 5); - { aes_32t i; - - for(i = 0; i < (13 * N_COLS - 7) / 6; ++i) - ke6(cx->ks, i); - kel6(cx->ks, 7); -#if !(DEC_ROUND == NO_TABLES) - for(i = N_COLS; i < 12 * N_COLS; ++i) - cx->ks[i] = inv_mcol(cx->ks[i]); -#endif - } -#else - cx->ks[4] = ff(ss[4] = word_in(key, 4)); - cx->ks[5] = ff(ss[5] = word_in(key, 5)); - kdf6(cx->ks, 0); kd6(cx->ks, 1); - kd6(cx->ks, 2); kd6(cx->ks, 3); - kd6(cx->ks, 4); kd6(cx->ks, 5); - kd6(cx->ks, 6); kdl6(cx->ks, 7); -#endif - cx->rn = 12; -#if defined( AES_ERR_CHK ) - return aes_good; -#endif -} - -#endif - -#if defined(AES_256) || defined(AES_VAR) - -aes_rval aes_decrypt_key256(const unsigned char *key, aes_decrypt_ctx cx[1]) -{ aes_32t ss[8]; -#if defined( d_vars ) - d_vars; -#endif - cx->ks[0] = ss[0] = word_in(key, 0); - cx->ks[1] = ss[1] = word_in(key, 1); - cx->ks[2] = ss[2] = word_in(key, 2); - cx->ks[3] = ss[3] = word_in(key, 3); - -#if DEC_UNROLL == NONE - cx->ks[4] = ss[4] = word_in(key, 4); - cx->ks[5] = ss[5] = word_in(key, 5); - cx->ks[6] = ss[6] = word_in(key, 6); - cx->ks[7] = ss[7] = word_in(key, 7); - { aes_32t i; - - for(i = 0; i < (15 * N_COLS - 9) / 8; ++i) - ke8(cx->ks, i); - kel8(cx->ks, i); -#if !(DEC_ROUND == NO_TABLES) - for(i = N_COLS; i < 14 * N_COLS; ++i) - cx->ks[i] = inv_mcol(cx->ks[i]); - -#endif - } -#else - cx->ks[4] = ff(ss[4] = word_in(key, 4)); - cx->ks[5] = ff(ss[5] = word_in(key, 5)); - cx->ks[6] = ff(ss[6] = word_in(key, 6)); - cx->ks[7] = ff(ss[7] = word_in(key, 7)); - kdf8(cx->ks, 0); kd8(cx->ks, 1); - kd8(cx->ks, 2); kd8(cx->ks, 3); - kd8(cx->ks, 4); kd8(cx->ks, 5); - kdl8(cx->ks, 6); -#endif - cx->rn = 14; -#if defined( AES_ERR_CHK ) - return aes_good; -#endif -} - -#endif - -#if defined(AES_VAR) - -aes_rval aes_decrypt_key(const unsigned char *key, int key_len, aes_decrypt_ctx cx[1]) -{ - switch(key_len) - { -#if defined( AES_ERR_CHK ) - case 16: case 128: return aes_decrypt_key128(key, cx); - case 24: case 192: return aes_decrypt_key192(key, cx); - case 32: case 256: return aes_decrypt_key256(key, cx); - default: return aes_error; -#else - case 16: case 128: aes_decrypt_key128(key, cx); return; - case 24: case 192: aes_decrypt_key192(key, cx); return; - case 32: case 256: aes_decrypt_key256(key, cx); return; -#endif - } -} - -#endif - -#endif - -#if defined(__cplusplus) -} -#endif +/* + --------------------------------------------------------------------------- + Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. + + LICENSE TERMS + + The free distribution and use of this software in both source and binary + form is allowed (with or without changes) provided that: + + 1. distributions of this source code include the above copyright + notice, this list of conditions and the following disclaimer; + + 2. distributions in binary form include the above copyright + notice, this list of conditions and the following disclaimer + in the documentation and/or other associated materials; + + 3. the copyright holder's name is not used to endorse products + built using this software without specific written permission. + + ALTERNATIVELY, provided that this notice is retained in full, this product + may be distributed under the terms of the GNU General Public License (GPL), + in which case the provisions of the GPL apply INSTEAD OF those given above. + + DISCLAIMER + + This software is provided 'as is' with no explicit or implied warranties + in respect of its properties, including, but not limited to, correctness + and/or fitness for purpose. + --------------------------------------------------------------------------- + Issue Date: 26/08/2003 + + This file contains the code for implementing the key schedule for AES + (Rijndael) for block and key sizes of 16, 24, and 32 bytes. See aesopt.h + for further details including optimisation. +*/ + +#include "aesopt.h" +#include "aestab.h" + +#if defined(__cplusplus) +extern "C" +{ +#endif + +/* Initialise the key schedule from the user supplied key. The key + length can be specified in bytes, with legal values of 16, 24 + and 32, or in bits, with legal values of 128, 192 and 256. These + values correspond with Nk values of 4, 6 and 8 respectively. + + The following macros implement a single cycle in the key + schedule generation process. The number of cycles needed + for each cx->n_col and nk value is: + + nk = 4 5 6 7 8 + ------------------------------ + cx->n_col = 4 10 9 8 7 7 + cx->n_col = 5 14 11 10 9 9 + cx->n_col = 6 19 15 12 11 11 + cx->n_col = 7 21 19 16 13 14 + cx->n_col = 8 29 23 19 17 14 +*/ + +#define ke4(k,i) \ +{ k[4*(i)+4] = ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+5] = ss[1] ^= ss[0]; \ + k[4*(i)+6] = ss[2] ^= ss[1]; k[4*(i)+7] = ss[3] ^= ss[2]; \ +} +#define kel4(k,i) \ +{ k[4*(i)+4] = ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+5] = ss[1] ^= ss[0]; \ + k[4*(i)+6] = ss[2] ^= ss[1]; k[4*(i)+7] = ss[3] ^= ss[2]; \ +} + +#define ke6(k,i) \ +{ k[6*(i)+ 6] = ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 7] = ss[1] ^= ss[0]; \ + k[6*(i)+ 8] = ss[2] ^= ss[1]; k[6*(i)+ 9] = ss[3] ^= ss[2]; \ + k[6*(i)+10] = ss[4] ^= ss[3]; k[6*(i)+11] = ss[5] ^= ss[4]; \ +} +#define kel6(k,i) \ +{ k[6*(i)+ 6] = ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 7] = ss[1] ^= ss[0]; \ + k[6*(i)+ 8] = ss[2] ^= ss[1]; k[6*(i)+ 9] = ss[3] ^= ss[2]; \ +} + +#define ke8(k,i) \ +{ k[8*(i)+ 8] = ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 9] = ss[1] ^= ss[0]; \ + k[8*(i)+10] = ss[2] ^= ss[1]; k[8*(i)+11] = ss[3] ^= ss[2]; \ + k[8*(i)+12] = ss[4] ^= ls_box(ss[3],0); k[8*(i)+13] = ss[5] ^= ss[4]; \ + k[8*(i)+14] = ss[6] ^= ss[5]; k[8*(i)+15] = ss[7] ^= ss[6]; \ +} +#define kel8(k,i) \ +{ k[8*(i)+ 8] = ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 9] = ss[1] ^= ss[0]; \ + k[8*(i)+10] = ss[2] ^= ss[1]; k[8*(i)+11] = ss[3] ^= ss[2]; \ +} + +#if defined(ENCRYPTION_KEY_SCHEDULE) + +#if defined(AES_128) || defined(AES_VAR) + +aes_rval aes_encrypt_key128(const unsigned char *key, aes_encrypt_ctx cx[1]) +{ aes_32t ss[4]; + + cx->ks[0] = ss[0] = word_in(key, 0); + cx->ks[1] = ss[1] = word_in(key, 1); + cx->ks[2] = ss[2] = word_in(key, 2); + cx->ks[3] = ss[3] = word_in(key, 3); + +#if ENC_UNROLL == NONE + { aes_32t i; + + for(i = 0; i < ((11 * N_COLS - 5) / 4); ++i) + ke4(cx->ks, i); + } +#else + ke4(cx->ks, 0); ke4(cx->ks, 1); + ke4(cx->ks, 2); ke4(cx->ks, 3); + ke4(cx->ks, 4); ke4(cx->ks, 5); + ke4(cx->ks, 6); ke4(cx->ks, 7); + ke4(cx->ks, 8); +#endif + kel4(cx->ks, 9); + cx->rn = 10; +#if defined( AES_ERR_CHK ) + return aes_good; +#endif +} + +#endif + +#if defined(AES_192) || defined(AES_VAR) + +aes_rval aes_encrypt_key192(const unsigned char *key, aes_encrypt_ctx cx[1]) +{ aes_32t ss[6]; + + cx->ks[0] = ss[0] = word_in(key, 0); + cx->ks[1] = ss[1] = word_in(key, 1); + cx->ks[2] = ss[2] = word_in(key, 2); + cx->ks[3] = ss[3] = word_in(key, 3); + cx->ks[4] = ss[4] = word_in(key, 4); + cx->ks[5] = ss[5] = word_in(key, 5); + +#if ENC_UNROLL == NONE + { aes_32t i; + + for(i = 0; i < (13 * N_COLS - 7) / 6; ++i) + ke6(cx->ks, i); + } +#else + ke6(cx->ks, 0); ke6(cx->ks, 1); + ke6(cx->ks, 2); ke6(cx->ks, 3); + ke6(cx->ks, 4); ke6(cx->ks, 5); + ke6(cx->ks, 6); +#endif + kel6(cx->ks, 7); + cx->rn = 12; +#if defined( AES_ERR_CHK ) + return aes_good; +#endif +} + +#endif + +#if defined(AES_256) || defined(AES_VAR) + +aes_rval aes_encrypt_key256(const unsigned char *key, aes_encrypt_ctx cx[1]) +{ aes_32t ss[8]; + + cx->ks[0] = ss[0] = word_in(key, 0); + cx->ks[1] = ss[1] = word_in(key, 1); + cx->ks[2] = ss[2] = word_in(key, 2); + cx->ks[3] = ss[3] = word_in(key, 3); + cx->ks[4] = ss[4] = word_in(key, 4); + cx->ks[5] = ss[5] = word_in(key, 5); + cx->ks[6] = ss[6] = word_in(key, 6); + cx->ks[7] = ss[7] = word_in(key, 7); + +#if ENC_UNROLL == NONE + { aes_32t i; + + for(i = 0; i < (15 * N_COLS - 9) / 8; ++i) + ke8(cx->ks, i); + } +#else + ke8(cx->ks, 0); ke8(cx->ks, 1); + ke8(cx->ks, 2); ke8(cx->ks, 3); + ke8(cx->ks, 4); ke8(cx->ks, 5); +#endif + kel8(cx->ks, 6); + cx->rn = 14; +#if defined( AES_ERR_CHK ) + return aes_good; +#endif +} + +#endif + +#if defined(AES_VAR) + +aes_rval aes_encrypt_key(const unsigned char *key, int key_len, aes_encrypt_ctx cx[1]) +{ + switch(key_len) + { +#if defined( AES_ERR_CHK ) + case 16: case 128: return aes_encrypt_key128(key, cx); + case 24: case 192: return aes_encrypt_key192(key, cx); + case 32: case 256: return aes_encrypt_key256(key, cx); + default: return aes_error; +#else + case 16: case 128: aes_encrypt_key128(key, cx); return; + case 24: case 192: aes_encrypt_key192(key, cx); return; + case 32: case 256: aes_encrypt_key256(key, cx); return; +#endif + } +} + +#endif + +#endif + +#if defined(DECRYPTION_KEY_SCHEDULE) + +#if DEC_ROUND == NO_TABLES +#define ff(x) (x) +#else +#define ff(x) inv_mcol(x) +#if defined( dec_imvars ) +#define d_vars dec_imvars +#endif +#endif + +#if 1 +#define kdf4(k,i) \ +{ ss[0] = ss[0] ^ ss[2] ^ ss[1] ^ ss[3]; ss[1] = ss[1] ^ ss[3]; ss[2] = ss[2] ^ ss[3]; ss[3] = ss[3]; \ + ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; \ + ss[4] ^= k[4*(i)]; k[4*(i)+4] = ff(ss[4]); ss[4] ^= k[4*(i)+1]; k[4*(i)+5] = ff(ss[4]); \ + ss[4] ^= k[4*(i)+2]; k[4*(i)+6] = ff(ss[4]); ss[4] ^= k[4*(i)+3]; k[4*(i)+7] = ff(ss[4]); \ +} +#define kd4(k,i) \ +{ ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; ss[4] = ff(ss[4]); \ + k[4*(i)+4] = ss[4] ^= k[4*(i)]; k[4*(i)+5] = ss[4] ^= k[4*(i)+1]; \ + k[4*(i)+6] = ss[4] ^= k[4*(i)+2]; k[4*(i)+7] = ss[4] ^= k[4*(i)+3]; \ +} +#define kdl4(k,i) \ +{ ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; \ + k[4*(i)+4] = (ss[0] ^= ss[1]) ^ ss[2] ^ ss[3]; k[4*(i)+5] = ss[1] ^ ss[3]; \ + k[4*(i)+6] = ss[0]; k[4*(i)+7] = ss[1]; \ +} +#else +#define kdf4(k,i) \ +{ ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+ 4] = ff(ss[0]); ss[1] ^= ss[0]; k[4*(i)+ 5] = ff(ss[1]); \ + ss[2] ^= ss[1]; k[4*(i)+ 6] = ff(ss[2]); ss[3] ^= ss[2]; k[4*(i)+ 7] = ff(ss[3]); \ +} +#define kd4(k,i) \ +{ ss[4] = ls_box(ss[3],3) ^ t_use(r,c)[i]; \ + ss[0] ^= ss[4]; ss[4] = ff(ss[4]); k[4*(i)+ 4] = ss[4] ^= k[4*(i)]; \ + ss[1] ^= ss[0]; k[4*(i)+ 5] = ss[4] ^= k[4*(i)+ 1]; \ + ss[2] ^= ss[1]; k[4*(i)+ 6] = ss[4] ^= k[4*(i)+ 2]; \ + ss[3] ^= ss[2]; k[4*(i)+ 7] = ss[4] ^= k[4*(i)+ 3]; \ +} +#define kdl4(k,i) \ +{ ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+ 4] = ss[0]; ss[1] ^= ss[0]; k[4*(i)+ 5] = ss[1]; \ + ss[2] ^= ss[1]; k[4*(i)+ 6] = ss[2]; ss[3] ^= ss[2]; k[4*(i)+ 7] = ss[3]; \ +} +#endif + +#define kdf6(k,i) \ +{ ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 6] = ff(ss[0]); ss[1] ^= ss[0]; k[6*(i)+ 7] = ff(ss[1]); \ + ss[2] ^= ss[1]; k[6*(i)+ 8] = ff(ss[2]); ss[3] ^= ss[2]; k[6*(i)+ 9] = ff(ss[3]); \ + ss[4] ^= ss[3]; k[6*(i)+10] = ff(ss[4]); ss[5] ^= ss[4]; k[6*(i)+11] = ff(ss[5]); \ +} +#define kd6(k,i) \ +{ ss[6] = ls_box(ss[5],3) ^ t_use(r,c)[i]; \ + ss[0] ^= ss[6]; ss[6] = ff(ss[6]); k[6*(i)+ 6] = ss[6] ^= k[6*(i)]; \ + ss[1] ^= ss[0]; k[6*(i)+ 7] = ss[6] ^= k[6*(i)+ 1]; \ + ss[2] ^= ss[1]; k[6*(i)+ 8] = ss[6] ^= k[6*(i)+ 2]; \ + ss[3] ^= ss[2]; k[6*(i)+ 9] = ss[6] ^= k[6*(i)+ 3]; \ + ss[4] ^= ss[3]; k[6*(i)+10] = ss[6] ^= k[6*(i)+ 4]; \ + ss[5] ^= ss[4]; k[6*(i)+11] = ss[6] ^= k[6*(i)+ 5]; \ +} +#define kdl6(k,i) \ +{ ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 6] = ss[0]; ss[1] ^= ss[0]; k[6*(i)+ 7] = ss[1]; \ + ss[2] ^= ss[1]; k[6*(i)+ 8] = ss[2]; ss[3] ^= ss[2]; k[6*(i)+ 9] = ss[3]; \ +} + +#define kdf8(k,i) \ +{ ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 8] = ff(ss[0]); ss[1] ^= ss[0]; k[8*(i)+ 9] = ff(ss[1]); \ + ss[2] ^= ss[1]; k[8*(i)+10] = ff(ss[2]); ss[3] ^= ss[2]; k[8*(i)+11] = ff(ss[3]); \ + ss[4] ^= ls_box(ss[3],0); k[8*(i)+12] = ff(ss[4]); ss[5] ^= ss[4]; k[8*(i)+13] = ff(ss[5]); \ + ss[6] ^= ss[5]; k[8*(i)+14] = ff(ss[6]); ss[7] ^= ss[6]; k[8*(i)+15] = ff(ss[7]); \ +} +#define kd8(k,i) \ +{ aes_32t g = ls_box(ss[7],3) ^ t_use(r,c)[i]; \ + ss[0] ^= g; g = ff(g); k[8*(i)+ 8] = g ^= k[8*(i)]; \ + ss[1] ^= ss[0]; k[8*(i)+ 9] = g ^= k[8*(i)+ 1]; \ + ss[2] ^= ss[1]; k[8*(i)+10] = g ^= k[8*(i)+ 2]; \ + ss[3] ^= ss[2]; k[8*(i)+11] = g ^= k[8*(i)+ 3]; \ + g = ls_box(ss[3],0); \ + ss[4] ^= g; g = ff(g); k[8*(i)+12] = g ^= k[8*(i)+ 4]; \ + ss[5] ^= ss[4]; k[8*(i)+13] = g ^= k[8*(i)+ 5]; \ + ss[6] ^= ss[5]; k[8*(i)+14] = g ^= k[8*(i)+ 6]; \ + ss[7] ^= ss[6]; k[8*(i)+15] = g ^= k[8*(i)+ 7]; \ +} +#define kdl8(k,i) \ +{ ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 8] = ss[0]; ss[1] ^= ss[0]; k[8*(i)+ 9] = ss[1]; \ + ss[2] ^= ss[1]; k[8*(i)+10] = ss[2]; ss[3] ^= ss[2]; k[8*(i)+11] = ss[3]; \ +} + +#if defined(AES_128) || defined(AES_VAR) + +aes_rval aes_decrypt_key128(const unsigned char *key, aes_decrypt_ctx cx[1]) +{ aes_32t ss[5]; +#if defined( d_vars ) + d_vars; +#endif + cx->ks[0] = ss[0] = word_in(key, 0); + cx->ks[1] = ss[1] = word_in(key, 1); + cx->ks[2] = ss[2] = word_in(key, 2); + cx->ks[3] = ss[3] = word_in(key, 3); + +#if DEC_UNROLL == NONE + { aes_32t i; + + for(i = 0; i < (11 * N_COLS - 5) / 4; ++i) + ke4(cx->ks, i); + kel4(cx->ks, 9); +#if !(DEC_ROUND == NO_TABLES) + for(i = N_COLS; i < 10 * N_COLS; ++i) + cx->ks[i] = inv_mcol(cx->ks[i]); +#endif + } +#else + kdf4(cx->ks, 0); kd4(cx->ks, 1); + kd4(cx->ks, 2); kd4(cx->ks, 3); + kd4(cx->ks, 4); kd4(cx->ks, 5); + kd4(cx->ks, 6); kd4(cx->ks, 7); + kd4(cx->ks, 8); kdl4(cx->ks, 9); +#endif + cx->rn = 10; +#if defined( AES_ERR_CHK ) + return aes_good; +#endif +} + +#endif + +#if defined(AES_192) || defined(AES_VAR) + +aes_rval aes_decrypt_key192(const unsigned char *key, aes_decrypt_ctx cx[1]) +{ aes_32t ss[7]; +#if defined( d_vars ) + d_vars; +#endif + cx->ks[0] = ss[0] = word_in(key, 0); + cx->ks[1] = ss[1] = word_in(key, 1); + cx->ks[2] = ss[2] = word_in(key, 2); + cx->ks[3] = ss[3] = word_in(key, 3); + +#if DEC_UNROLL == NONE + cx->ks[4] = ss[4] = word_in(key, 4); + cx->ks[5] = ss[5] = word_in(key, 5); + { aes_32t i; + + for(i = 0; i < (13 * N_COLS - 7) / 6; ++i) + ke6(cx->ks, i); + kel6(cx->ks, 7); +#if !(DEC_ROUND == NO_TABLES) + for(i = N_COLS; i < 12 * N_COLS; ++i) + cx->ks[i] = inv_mcol(cx->ks[i]); +#endif + } +#else + cx->ks[4] = ff(ss[4] = word_in(key, 4)); + cx->ks[5] = ff(ss[5] = word_in(key, 5)); + kdf6(cx->ks, 0); kd6(cx->ks, 1); + kd6(cx->ks, 2); kd6(cx->ks, 3); + kd6(cx->ks, 4); kd6(cx->ks, 5); + kd6(cx->ks, 6); kdl6(cx->ks, 7); +#endif + cx->rn = 12; +#if defined( AES_ERR_CHK ) + return aes_good; +#endif +} + +#endif + +#if defined(AES_256) || defined(AES_VAR) + +aes_rval aes_decrypt_key256(const unsigned char *key, aes_decrypt_ctx cx[1]) +{ aes_32t ss[8]; +#if defined( d_vars ) + d_vars; +#endif + cx->ks[0] = ss[0] = word_in(key, 0); + cx->ks[1] = ss[1] = word_in(key, 1); + cx->ks[2] = ss[2] = word_in(key, 2); + cx->ks[3] = ss[3] = word_in(key, 3); + +#if DEC_UNROLL == NONE + cx->ks[4] = ss[4] = word_in(key, 4); + cx->ks[5] = ss[5] = word_in(key, 5); + cx->ks[6] = ss[6] = word_in(key, 6); + cx->ks[7] = ss[7] = word_in(key, 7); + { aes_32t i; + + for(i = 0; i < (15 * N_COLS - 9) / 8; ++i) + ke8(cx->ks, i); + kel8(cx->ks, i); +#if !(DEC_ROUND == NO_TABLES) + for(i = N_COLS; i < 14 * N_COLS; ++i) + cx->ks[i] = inv_mcol(cx->ks[i]); + +#endif + } +#else + cx->ks[4] = ff(ss[4] = word_in(key, 4)); + cx->ks[5] = ff(ss[5] = word_in(key, 5)); + cx->ks[6] = ff(ss[6] = word_in(key, 6)); + cx->ks[7] = ff(ss[7] = word_in(key, 7)); + kdf8(cx->ks, 0); kd8(cx->ks, 1); + kd8(cx->ks, 2); kd8(cx->ks, 3); + kd8(cx->ks, 4); kd8(cx->ks, 5); + kdl8(cx->ks, 6); +#endif + cx->rn = 14; +#if defined( AES_ERR_CHK ) + return aes_good; +#endif +} + +#endif + +#if defined(AES_VAR) + +aes_rval aes_decrypt_key(const unsigned char *key, int key_len, aes_decrypt_ctx cx[1]) +{ + switch(key_len) + { +#if defined( AES_ERR_CHK ) + case 16: case 128: return aes_decrypt_key128(key, cx); + case 24: case 192: return aes_decrypt_key192(key, cx); + case 32: case 256: return aes_decrypt_key256(key, cx); + default: return aes_error; +#else + case 16: case 128: aes_decrypt_key128(key, cx); return; + case 24: case 192: aes_decrypt_key192(key, cx); return; + case 32: case 256: aes_decrypt_key256(key, cx); return; +#endif + } +} + +#endif + +#endif + +#if defined(__cplusplus) +} +#endif diff --git a/bsd/crypto/aes/aesopt.h b/bsd/crypto/aes/aesopt.h index 7b2ea04f0..976ae902c 100644 --- a/bsd/crypto/aes/aesopt.h +++ b/bsd/crypto/aes/aesopt.h @@ -1,753 +1,753 @@ -/* - --------------------------------------------------------------------------- - Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. - - LICENSE TERMS - - The free distribution and use of this software in both source and binary - form is allowed (with or without changes) provided that: - - 1. distributions of this source code include the above copyright - notice, this list of conditions and the following disclaimer; - - 2. distributions in binary form include the above copyright - notice, this list of conditions and the following disclaimer - in the documentation and/or other associated materials; - - 3. the copyright holder's name is not used to endorse products - built using this software without specific written permission. - - ALTERNATIVELY, provided that this notice is retained in full, this product - may be distributed under the terms of the GNU General Public License (GPL), - in which case the provisions of the GPL apply INSTEAD OF those given above. - - DISCLAIMER - - This software is provided 'as is' with no explicit or implied warranties - in respect of its properties, including, but not limited to, correctness - and/or fitness for purpose. - --------------------------------------------------------------------------- - Issue 28/01/2004 - - My thanks go to Dag Arne Osvik for devising the schemes used here for key - length derivation from the form of the key schedule - - This file contains the compilation options for AES (Rijndael) and code - that is common across encryption, key scheduling and table generation. - - OPERATION - - These source code files implement the AES algorithm Rijndael designed by - Joan Daemen and Vincent Rijmen. This version is designed for the standard - block size of 16 bytes and for key sizes of 128, 192 and 256 bits (16, 24 - and 32 bytes). - - This version is designed for flexibility and speed using operations on - 32-bit words rather than operations on bytes. It can be compiled with - either big or little endian internal byte order but is faster when the - native byte order for the processor is used. - - THE CIPHER INTERFACE - - The cipher interface is implemented as an array of bytes in which lower - AES bit sequence indexes map to higher numeric significance within bytes. - - aes_08t (an unsigned 8-bit type) - aes_32t (an unsigned 32-bit type) - struct aes_encrypt_ctx (structure for the cipher encryption context) - struct aes_decrypt_ctx (structure for the cipher decryption context) - aes_rval the function return type - - C subroutine calls: - - aes_rval aes_encrypt_key128(const unsigned char *key, aes_encrypt_ctx cx[1]); - aes_rval aes_encrypt_key192(const unsigned char *key, aes_encrypt_ctx cx[1]); - aes_rval aes_encrypt_key256(const unsigned char *key, aes_encrypt_ctx cx[1]); - aes_rval aes_encrypt(const unsigned char *in, unsigned char *out, - const aes_encrypt_ctx cx[1]); - - aes_rval aes_decrypt_key128(const unsigned char *key, aes_decrypt_ctx cx[1]); - aes_rval aes_decrypt_key192(const unsigned char *key, aes_decrypt_ctx cx[1]); - aes_rval aes_decrypt_key256(const unsigned char *key, aes_decrypt_ctx cx[1]); - aes_rval aes_decrypt(const unsigned char *in, unsigned char *out, - const aes_decrypt_ctx cx[1]); - - IMPORTANT NOTE: If you are using this C interface with dynamic tables make sure that - you call genTabs() before AES is used so that the tables are initialised. - - C++ aes class subroutines: - - Class AESencrypt for encryption - - Construtors: - AESencrypt(void) - AESencrypt(const unsigned char *key) - 128 bit key - Members: - aes_rval key128(const unsigned char *key) - aes_rval key192(const unsigned char *key) - aes_rval key256(const unsigned char *key) - aes_rval encrypt(const unsigned char *in, unsigned char *out) const - - Class AESdecrypt for encryption - Construtors: - AESdecrypt(void) - AESdecrypt(const unsigned char *key) - 128 bit key - Members: - aes_rval key128(const unsigned char *key) - aes_rval key192(const unsigned char *key) - aes_rval key256(const unsigned char *key) - aes_rval decrypt(const unsigned char *in, unsigned char *out) const - - COMPILATION - - The files used to provide AES (Rijndael) are - - a. aes.h for the definitions needed for use in C. - b. aescpp.h for the definitions needed for use in C++. - c. aesopt.h for setting compilation options (also includes common code). - d. aescrypt.c for encryption and decrytpion, or - e. aeskey.c for key scheduling. - f. aestab.c for table loading or generation. - g. aescrypt.asm for encryption and decryption using assembler code. - h. aescrypt.mmx.asm for encryption and decryption using MMX assembler. - - To compile AES (Rijndael) for use in C code use aes.h and set the - defines here for the facilities you need (key lengths, encryption - and/or decryption). Do not define AES_DLL or AES_CPP. Set the options - for optimisations and table sizes here. - - To compile AES (Rijndael) for use in in C++ code use aescpp.h but do - not define AES_DLL - - To compile AES (Rijndael) in C as a Dynamic Link Library DLL) use - aes.h and include the AES_DLL define. - - CONFIGURATION OPTIONS (here and in aes.h) - - a. set AES_DLL in aes.h if AES (Rijndael) is to be compiled as a DLL - b. You may need to set PLATFORM_BYTE_ORDER to define the byte order. - c. If you want the code to run in a specific internal byte order, then - ALGORITHM_BYTE_ORDER must be set accordingly. - d. set other configuration options decribed below. -*/ - -#if !defined( _AESOPT_H ) -#define _AESOPT_H - -#include "aes.h" - -/* CONFIGURATION - USE OF DEFINES - - Later in this section there are a number of defines that control the - operation of the code. In each section, the purpose of each define is - explained so that the relevant form can be included or excluded by - setting either 1's or 0's respectively on the branches of the related - #if clauses. - - PLATFORM SPECIFIC INCLUDES AND BYTE ORDER IN 32-BIT WORDS - - To obtain the highest speed on processors with 32-bit words, this code - needs to determine the byte order of the target machine. The following - block of code is an attempt to capture the most obvious ways in which - various environemnts define byte order. It may well fail, in which case - the definitions will need to be set by editing at the points marked - **** EDIT HERE IF NECESSARY **** below. My thanks go to Peter Gutmann - for his assistance with this endian detection nightmare. -*/ - -#define BRG_LITTLE_ENDIAN 1234 /* byte 0 is least significant (i386) */ -#define BRG_BIG_ENDIAN 4321 /* byte 0 is most significant (mc68k) */ - -#if defined(__GNUC__) || defined(__GNU_LIBRARY__) -# if defined(__FreeBSD__) || defined(__OpenBSD__) -# include <sys/endian.h> -# elif defined( BSD ) && BSD >= 199103 -# include <machine/endian.h> -# elif defined(__APPLE__) -# if defined(__BIG_ENDIAN__) && !defined( BIG_ENDIAN ) -# define BIG_ENDIAN -# elif defined(__LITTLE_ENDIAN__) && !defined( LITTLE_ENDIAN ) -# define LITTLE_ENDIAN -# endif -# else -# include <endian.h> -# if defined(__BEOS__) -# include <byteswap.h> -# endif -# endif -#endif - -#if !defined(PLATFORM_BYTE_ORDER) -# if defined(LITTLE_ENDIAN) || defined(BIG_ENDIAN) -# if defined(LITTLE_ENDIAN) && !defined(BIG_ENDIAN) -# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN -# elif !defined(LITTLE_ENDIAN) && defined(BIG_ENDIAN) -# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN -# elif defined(BYTE_ORDER) && (BYTE_ORDER == LITTLE_ENDIAN) -# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN -# elif defined(BYTE_ORDER) && (BYTE_ORDER == BIG_ENDIAN) -# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN -# endif -# elif defined(_LITTLE_ENDIAN) || defined(_BIG_ENDIAN) -# if defined(_LITTLE_ENDIAN) && !defined(_BIG_ENDIAN) -# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN -# elif !defined(_LITTLE_ENDIAN) && defined(_BIG_ENDIAN) -# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN -# elif defined(_BYTE_ORDER) && (_BYTE_ORDER == _LITTLE_ENDIAN) -# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN -# elif defined(_BYTE_ORDER) && (_BYTE_ORDER == _BIG_ENDIAN) -# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN -# endif -# elif defined(__LITTLE_ENDIAN__) || defined(__BIG_ENDIAN__) -# if defined(__LITTLE_ENDIAN__) && !defined(__BIG_ENDIAN__) -# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN -# elif !defined(__LITTLE_ENDIAN__) && defined(__BIG_ENDIAN__) -# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN -# elif defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __LITTLE_ENDIAN__) -# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN -# elif defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __BIG_ENDIAN__) -# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN -# endif -# endif -#endif - -/* if the platform is still unknown, try to find its byte order */ -/* from commonly used machine defines */ - -#if !defined(PLATFORM_BYTE_ORDER) - -#if defined( __alpha__ ) || defined( __alpha ) || defined( i386 ) || \ - defined( __i386__ ) || defined( _M_I86 ) || defined( _M_IX86 ) || \ - defined( __OS2__ ) || defined( sun386 ) || defined( __TURBOC__ ) || \ - defined( vax ) || defined( vms ) || defined( VMS ) || \ - defined( __VMS ) -# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN - -#elif defined( AMIGA ) || defined( applec ) || defined( __AS400__ ) || \ - defined( _CRAY ) || defined( __hppa ) || defined( __hp9000 ) || \ - defined( ibm370 ) || defined( mc68000 ) || defined( m68k ) || \ - defined( __MRC__ ) || defined( __MVS__ ) || defined( __MWERKS__ ) || \ - defined( sparc ) || defined( __sparc) || defined( SYMANTEC_C ) || \ - defined( __TANDEM ) || defined( THINK_C ) || defined( __VMCMS__ ) -# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN - -#elif 0 /* **** EDIT HERE IF NECESSARY **** */ -# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN -#elif 0 /* **** EDIT HERE IF NECESSARY **** */ -# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN -#else -# error Please edit aesopt.h (line 234 or 236) to set the platform byte order -#endif - -#endif - -/* SOME LOCAL DEFINITIONS */ - -#define NO_TABLES 0 -#define ONE_TABLE 1 -#define FOUR_TABLES 4 -#define NONE 0 -#define PARTIAL 1 -#define FULL 2 - -#if defined(bswap32) -#define aes_sw32 bswap32 -#elif defined(bswap_32) -#define aes_sw32 bswap_32 -#else -#define brot(x,n) (((aes_32t)(x) << n) | ((aes_32t)(x) >> (32 - n))) -#define aes_sw32(x) ((brot((x),8) & 0x00ff00ff) | (brot((x),24) & 0xff00ff00)) -#endif - -/* 1. FUNCTIONS REQUIRED - - This implementation provides subroutines for encryption, decryption - and for setting the three key lengths (separately) for encryption - and decryption. When the assembler code is not being used the following - definition blocks allow the selection of the routines that are to be - included in the compilation. -*/ -#if defined( AES_ENCRYPT ) -#define ENCRYPTION -#define ENCRYPTION_KEY_SCHEDULE -#endif - -#if defined( AES_DECRYPT ) -#define DECRYPTION -#define DECRYPTION_KEY_SCHEDULE -#endif - -/* 2. ASSEMBLER SUPPORT - - This define (which can be on the command line) enables the use of the - assembler code routines for encryption and decryption with the C code - only providing key scheduling -*/ -#if 0 && !defined(AES_ASM) -#define AES_ASM -#endif - -/* 3. BYTE ORDER WITHIN 32 BIT WORDS - - The fundamental data processing units in Rijndael are 8-bit bytes. The - input, output and key input are all enumerated arrays of bytes in which - bytes are numbered starting at zero and increasing to one less than the - number of bytes in the array in question. This enumeration is only used - for naming bytes and does not imply any adjacency or order relationship - from one byte to another. When these inputs and outputs are considered - as bit sequences, bits 8*n to 8*n+7 of the bit sequence are mapped to - byte[n] with bit 8n+i in the sequence mapped to bit 7-i within the byte. - In this implementation bits are numbered from 0 to 7 starting at the - numerically least significant end of each byte (bit n represents 2^n). - - However, Rijndael can be implemented more efficiently using 32-bit - words by packing bytes into words so that bytes 4*n to 4*n+3 are placed - into word[n]. While in principle these bytes can be assembled into words - in any positions, this implementation only supports the two formats in - which bytes in adjacent positions within words also have adjacent byte - numbers. This order is called big-endian if the lowest numbered bytes - in words have the highest numeric significance and little-endian if the - opposite applies. - - This code can work in either order irrespective of the order used by the - machine on which it runs. Normally the internal byte order will be set - to the order of the processor on which the code is to be run but this - define can be used to reverse this in special situations - - NOTE: Assembler code versions rely on PLATFORM_BYTE_ORDER being set -*/ -#if 1 || defined(AES_ASM) -#define ALGORITHM_BYTE_ORDER PLATFORM_BYTE_ORDER -#elif 0 -#define ALGORITHM_BYTE_ORDER BRG_LITTLE_ENDIAN -#elif 0 -#define ALGORITHM_BYTE_ORDER BRG_BIG_ENDIAN -#else -#error The algorithm byte order is not defined -#endif - -/* 4. FAST INPUT/OUTPUT OPERATIONS. - - On some machines it is possible to improve speed by transferring the - bytes in the input and output arrays to and from the internal 32-bit - variables by addressing these arrays as if they are arrays of 32-bit - words. On some machines this will always be possible but there may - be a large performance penalty if the byte arrays are not aligned on - the normal word boundaries. On other machines this technique will - lead to memory access errors when such 32-bit word accesses are not - properly aligned. The option SAFE_IO avoids such problems but will - often be slower on those machines that support misaligned access - (especially so if care is taken to align the input and output byte - arrays on 32-bit word boundaries). If SAFE_IO is not defined it is - assumed that access to byte arrays as if they are arrays of 32-bit - words will not cause problems when such accesses are misaligned. -*/ -#if 0 && !defined(_MSC_VER) -#define SAFE_IO -#endif - -/* 5. LOOP UNROLLING - - The code for encryption and decrytpion cycles through a number of rounds - that can be implemented either in a loop or by expanding the code into a - long sequence of instructions, the latter producing a larger program but - one that will often be much faster. The latter is called loop unrolling. - There are also potential speed advantages in expanding two iterations in - a loop with half the number of iterations, which is called partial loop - unrolling. The following options allow partial or full loop unrolling - to be set independently for encryption and decryption -*/ -#if 1 -#define ENC_UNROLL FULL -#elif 0 -#define ENC_UNROLL PARTIAL -#else -#define ENC_UNROLL NONE -#endif - -#if 1 -#define DEC_UNROLL FULL -#elif 0 -#define DEC_UNROLL PARTIAL -#else -#define DEC_UNROLL NONE -#endif - -/* 6. FAST FINITE FIELD OPERATIONS - - If this section is included, tables are used to provide faster finite - field arithmetic (this has no effect if FIXED_TABLES is defined). -*/ -#if 1 -#define FF_TABLES -#endif - -/* 7. INTERNAL STATE VARIABLE FORMAT - - The internal state of Rijndael is stored in a number of local 32-bit - word varaibles which can be defined either as an array or as individual - names variables. Include this section if you want to store these local - varaibles in arrays. Otherwise individual local variables will be used. -*/ -#if 0 -#define ARRAYS -#endif - -/* In this implementation the columns of the state array are each held in - 32-bit words. The state array can be held in various ways: in an array - of words, in a number of individual word variables or in a number of - processor registers. The following define maps a variable name x and - a column number c to the way the state array variable is to be held. - The first define below maps the state into an array x[c] whereas the - second form maps the state into a number of individual variables x0, - x1, etc. Another form could map individual state colums to machine - register names. -*/ - -#if defined(ARRAYS) -#define s(x,c) x[c] -#else -#define s(x,c) x##c -#endif - -/* 8. FIXED OR DYNAMIC TABLES - - When this section is included the tables used by the code are compiled - statically into the binary file. Otherwise the subroutine gen_tabs() - must be called to compute them before the code is first used. -*/ -#if 1 -#define FIXED_TABLES -#endif - -/* 9. TABLE ALIGNMENT - - On some sytsems speed will be improved by aligning the AES large lookup - tables on particular boundaries. This define should be set to a power of - two giving the desired alignment. It can be left undefined if alignment - is not needed. This option is specific to the Microsft VC++ compiler - - it seems to sometimes cause trouble for the VC++ version 6 compiler. -*/ - -#if 0 && defined(_MSC_VER) && (_MSC_VER >= 1300) -#define TABLE_ALIGN 64 -#endif - -/* 10. INTERNAL TABLE CONFIGURATION - - This cipher proceeds by repeating in a number of cycles known as 'rounds' - which are implemented by a round function which can optionally be speeded - up using tables. The basic tables are each 256 32-bit words, with either - one or four tables being required for each round function depending on - how much speed is required. The encryption and decryption round functions - are different and the last encryption and decrytpion round functions are - different again making four different round functions in all. - - This means that: - 1. Normal encryption and decryption rounds can each use either 0, 1 - or 4 tables and table spaces of 0, 1024 or 4096 bytes each. - 2. The last encryption and decryption rounds can also use either 0, 1 - or 4 tables and table spaces of 0, 1024 or 4096 bytes each. - - Include or exclude the appropriate definitions below to set the number - of tables used by this implementation. -*/ - -#if 1 /* set tables for the normal encryption round */ -#define ENC_ROUND FOUR_TABLES -#elif 0 -#define ENC_ROUND ONE_TABLE -#else -#define ENC_ROUND NO_TABLES -#endif - -#if 1 /* set tables for the last encryption round */ -#define LAST_ENC_ROUND FOUR_TABLES -#elif 0 -#define LAST_ENC_ROUND ONE_TABLE -#else -#define LAST_ENC_ROUND NO_TABLES -#endif - -#if 1 /* set tables for the normal decryption round */ -#define DEC_ROUND FOUR_TABLES -#elif 0 -#define DEC_ROUND ONE_TABLE -#else -#define DEC_ROUND NO_TABLES -#endif - -#if 1 /* set tables for the last decryption round */ -#define LAST_DEC_ROUND FOUR_TABLES -#elif 0 -#define LAST_DEC_ROUND ONE_TABLE -#else -#define LAST_DEC_ROUND NO_TABLES -#endif - -/* The decryption key schedule can be speeded up with tables in the same - way that the round functions can. Include or exclude the following - defines to set this requirement. -*/ -#if 1 -#define KEY_SCHED FOUR_TABLES -#elif 0 -#define KEY_SCHED ONE_TABLE -#else -#define KEY_SCHED NO_TABLES -#endif - -/* 11. TABLE POINTER CACHING - - Normally tables are referenced directly, Enable this option if you wish to - cache pointers to the tables in the encrypt/decrypt code. Note that this - only works if you are using FOUR_TABLES for the ROUND you enable this for. -*/ -#if 1 -#define ENC_ROUND_CACHE_TABLES -#endif -#if 1 -#define LAST_ENC_ROUND_CACHE_TABLES -#endif -#if 1 -#define DEC_ROUND_CACHE_TABLES -#endif -#if 1 -#define LAST_DEC_ROUND_CACHE_TABLES -#endif - - -/* END OF CONFIGURATION OPTIONS */ - -#define RC_LENGTH (5 * (AES_BLOCK_SIZE / 4 - 2)) - -/* Disable or report errors on some combinations of options */ - -#if ENC_ROUND == NO_TABLES && LAST_ENC_ROUND != NO_TABLES -#undef LAST_ENC_ROUND -#define LAST_ENC_ROUND NO_TABLES -#elif ENC_ROUND == ONE_TABLE && LAST_ENC_ROUND == FOUR_TABLES -#undef LAST_ENC_ROUND -#define LAST_ENC_ROUND ONE_TABLE -#endif - -#if ENC_ROUND == NO_TABLES && ENC_UNROLL != NONE -#undef ENC_UNROLL -#define ENC_UNROLL NONE -#endif - -#if DEC_ROUND == NO_TABLES && LAST_DEC_ROUND != NO_TABLES -#undef LAST_DEC_ROUND -#define LAST_DEC_ROUND NO_TABLES -#elif DEC_ROUND == ONE_TABLE && LAST_DEC_ROUND == FOUR_TABLES -#undef LAST_DEC_ROUND -#define LAST_DEC_ROUND ONE_TABLE -#endif - -#if DEC_ROUND == NO_TABLES && DEC_UNROLL != NONE -#undef DEC_UNROLL -#define DEC_UNROLL NONE -#endif - -/* upr(x,n): rotates bytes within words by n positions, moving bytes to - higher index positions with wrap around into low positions - ups(x,n): moves bytes by n positions to higher index positions in - words but without wrap around - bval(x,n): extracts a byte from a word - - NOTE: The definitions given here are intended only for use with - unsigned variables and with shift counts that are compile - time constants -*/ - -#if (ALGORITHM_BYTE_ORDER == BRG_LITTLE_ENDIAN) -#define upr(x,n) (((aes_32t)(x) << (8 * (n))) | ((aes_32t)(x) >> (32 - 8 * (n)))) -#define ups(x,n) ((aes_32t) (x) << (8 * (n))) -#define bval(x,n) ((aes_08t)((x) >> (8 * (n)))) -#define bytes2word(b0, b1, b2, b3) \ - (((aes_32t)(b3) << 24) | ((aes_32t)(b2) << 16) | ((aes_32t)(b1) << 8) | (b0)) -#endif - -#if (ALGORITHM_BYTE_ORDER == BRG_BIG_ENDIAN) -#define upr(x,n) (((aes_32t)(x) >> (8 * (n))) | ((aes_32t)(x) << (32 - 8 * (n)))) -#define ups(x,n) ((aes_32t) (x) >> (8 * (n)))) -#define bval(x,n) ((aes_08t)((x) >> (24 - 8 * (n)))) -#define bytes2word(b0, b1, b2, b3) \ - (((aes_32t)(b0) << 24) | ((aes_32t)(b1) << 16) | ((aes_32t)(b2) << 8) | (b3)) -#endif - -#if defined(SAFE_IO) - -#define word_in(x,c) bytes2word(((aes_08t*)(x)+4*c)[0], ((aes_08t*)(x)+4*c)[1], \ - ((aes_08t*)(x)+4*c)[2], ((aes_08t*)(x)+4*c)[3]) -#define word_out(x,c,v) { ((aes_08t*)(x)+4*c)[0] = bval(v,0); ((aes_08t*)(x)+4*c)[1] = bval(v,1); \ - ((aes_08t*)(x)+4*c)[2] = bval(v,2); ((aes_08t*)(x)+4*c)[3] = bval(v,3); } - -#elif (ALGORITHM_BYTE_ORDER == PLATFORM_BYTE_ORDER) - -#define word_in(x,c) (*((aes_32t*)(x)+(c))) -#define word_out(x,c,v) (*((aes_32t*)(x)+(c)) = (v)) - -#else - -#define word_in(x,c) aes_sw32(*((aes_32t*)(x)+(c))) -#define word_out(x,c,v) (*((aes_32t*)(x)+(c)) = aes_sw32(v)) - -#endif - -/* the finite field modular polynomial and elements */ - -#define WPOLY 0x011b -#define BPOLY 0x1b - -/* multiply four bytes in GF(2^8) by 'x' {02} in parallel */ - -#define m1 0x80808080 -#define m2 0x7f7f7f7f -#define gf_mulx(x) ((((x) & m2) << 1) ^ ((((x) & m1) >> 7) * BPOLY)) - -/* The following defines provide alternative definitions of gf_mulx that might - give improved performance if a fast 32-bit multiply is not available. Note - that a temporary variable u needs to be defined where gf_mulx is used. - -#define gf_mulx(x) (u = (x) & m1, u |= (u >> 1), ((x) & m2) << 1) ^ ((u >> 3) | (u >> 6)) -#define m4 (0x01010101 * BPOLY) -#define gf_mulx(x) (u = (x) & m1, ((x) & m2) << 1) ^ ((u - (u >> 7)) & m4) -*/ - -/* Work out which tables are needed for the different options */ - -#if defined( AES_ASM ) -#if defined( ENC_ROUND ) -#undef ENC_ROUND -#endif -#define ENC_ROUND FOUR_TABLES -#if defined( LAST_ENC_ROUND ) -#undef LAST_ENC_ROUND -#endif -#define LAST_ENC_ROUND FOUR_TABLES -#if defined( DEC_ROUND ) -#undef DEC_ROUND -#endif -#define DEC_ROUND FOUR_TABLES -#if defined( LAST_DEC_ROUND ) -#undef LAST_DEC_ROUND -#endif -#define LAST_DEC_ROUND FOUR_TABLES -#if defined( KEY_SCHED ) -#undef KEY_SCHED -#define KEY_SCHED FOUR_TABLES -#endif -#endif - -#if defined(ENCRYPTION) || defined(AES_ASM) -#if ENC_ROUND == ONE_TABLE -#define FT1_SET -#elif ENC_ROUND == FOUR_TABLES -#define FT4_SET -#else -#define SBX_SET -#endif -#if LAST_ENC_ROUND == ONE_TABLE -#define FL1_SET -#elif LAST_ENC_ROUND == FOUR_TABLES -#define FL4_SET -#elif !defined(SBX_SET) -#define SBX_SET -#endif -#endif - -#if defined(DECRYPTION) || defined(AES_ASM) -#if DEC_ROUND == ONE_TABLE -#define IT1_SET -#elif DEC_ROUND == FOUR_TABLES -#define IT4_SET -#else -#define ISB_SET -#endif -#if LAST_DEC_ROUND == ONE_TABLE -#define IL1_SET -#elif LAST_DEC_ROUND == FOUR_TABLES -#define IL4_SET -#elif !defined(ISB_SET) -#define ISB_SET -#endif -#endif - -#if defined(ENCRYPTION_KEY_SCHEDULE) || defined(DECRYPTION_KEY_SCHEDULE) -#if KEY_SCHED == ONE_TABLE -#define LS1_SET -#define IM1_SET -#elif KEY_SCHED == FOUR_TABLES -#define LS4_SET -#define IM4_SET -#elif !defined(SBX_SET) -#define SBX_SET -#endif -#endif - -/* generic definitions of Rijndael macros that use tables */ - -#define no_table(x,box,vf,rf,c) bytes2word( \ - box[bval(vf(x,0,c),rf(0,c))], \ - box[bval(vf(x,1,c),rf(1,c))], \ - box[bval(vf(x,2,c),rf(2,c))], \ - box[bval(vf(x,3,c),rf(3,c))]) - -#define one_table(x,op,tab,vf,rf,c) \ - ( tab[bval(vf(x,0,c),rf(0,c))] \ - ^ op(tab[bval(vf(x,1,c),rf(1,c))],1) \ - ^ op(tab[bval(vf(x,2,c),rf(2,c))],2) \ - ^ op(tab[bval(vf(x,3,c),rf(3,c))],3)) - -#define four_tables(x,tab,vf,rf,c) \ - ( tab[0][bval(vf(x,0,c),rf(0,c))] \ - ^ tab[1][bval(vf(x,1,c),rf(1,c))] \ - ^ tab[2][bval(vf(x,2,c),rf(2,c))] \ - ^ tab[3][bval(vf(x,3,c),rf(3,c))]) - -#define four_cached_tables(x,tab,vf,rf,c) \ -( tab##0[bval(vf(x,0,c),rf(0,c))] \ - ^ tab##1[bval(vf(x,1,c),rf(1,c))] \ - ^ tab##2[bval(vf(x,2,c),rf(2,c))] \ - ^ tab##3[bval(vf(x,3,c),rf(3,c))]) - -#define vf1(x,r,c) (x) -#define rf1(r,c) (r) -#define rf2(r,c) ((8+r-c)&3) - -/* perform forward and inverse column mix operation on four bytes in long word x in */ -/* parallel. NOTE: x must be a simple variable, NOT an expression in these macros. */ - -#if defined(FM4_SET) /* not currently used */ -#define fwd_mcol(x) four_tables(x,t_use(f,m),vf1,rf1,0) -#elif defined(FM1_SET) /* not currently used */ -#define fwd_mcol(x) one_table(x,upr,t_use(f,m),vf1,rf1,0) -#else -#define dec_fmvars aes_32t g2 -#define fwd_mcol(x) (g2 = gf_mulx(x), g2 ^ upr((x) ^ g2, 3) ^ upr((x), 2) ^ upr((x), 1)) -#endif - -#if defined(IM4_SET) -#define inv_mcol(x) four_tables(x,t_use(i,m),vf1,rf1,0) -#elif defined(IM1_SET) -#define inv_mcol(x) one_table(x,upr,t_use(i,m),vf1,rf1,0) -#else -#define dec_imvars aes_32t g2, g4, g9 -#define inv_mcol(x) (g2 = gf_mulx(x), g4 = gf_mulx(g2), g9 = (x) ^ gf_mulx(g4), g4 ^= g9, \ - (x) ^ g2 ^ g4 ^ upr(g2 ^ g9, 3) ^ upr(g4, 2) ^ upr(g9, 1)) -#endif - -#if defined(FL4_SET) -#define ls_box(x,c) four_tables(x,t_use(f,l),vf1,rf2,c) -#elif defined(LS4_SET) -#define ls_box(x,c) four_tables(x,t_use(l,s),vf1,rf2,c) -#elif defined(FL1_SET) -#define ls_box(x,c) one_table(x,upr,t_use(f,l),vf1,rf2,c) -#elif defined(LS1_SET) -#define ls_box(x,c) one_table(x,upr,t_use(l,s),vf1,rf2,c) -#else -#define ls_box(x,c) no_table(x,t_use(s,box),vf1,rf2,c) -#endif - -#endif +/* + --------------------------------------------------------------------------- + Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. + + LICENSE TERMS + + The free distribution and use of this software in both source and binary + form is allowed (with or without changes) provided that: + + 1. distributions of this source code include the above copyright + notice, this list of conditions and the following disclaimer; + + 2. distributions in binary form include the above copyright + notice, this list of conditions and the following disclaimer + in the documentation and/or other associated materials; + + 3. the copyright holder's name is not used to endorse products + built using this software without specific written permission. + + ALTERNATIVELY, provided that this notice is retained in full, this product + may be distributed under the terms of the GNU General Public License (GPL), + in which case the provisions of the GPL apply INSTEAD OF those given above. + + DISCLAIMER + + This software is provided 'as is' with no explicit or implied warranties + in respect of its properties, including, but not limited to, correctness + and/or fitness for purpose. + --------------------------------------------------------------------------- + Issue 28/01/2004 + + My thanks go to Dag Arne Osvik for devising the schemes used here for key + length derivation from the form of the key schedule + + This file contains the compilation options for AES (Rijndael) and code + that is common across encryption, key scheduling and table generation. + + OPERATION + + These source code files implement the AES algorithm Rijndael designed by + Joan Daemen and Vincent Rijmen. This version is designed for the standard + block size of 16 bytes and for key sizes of 128, 192 and 256 bits (16, 24 + and 32 bytes). + + This version is designed for flexibility and speed using operations on + 32-bit words rather than operations on bytes. It can be compiled with + either big or little endian internal byte order but is faster when the + native byte order for the processor is used. + + THE CIPHER INTERFACE + + The cipher interface is implemented as an array of bytes in which lower + AES bit sequence indexes map to higher numeric significance within bytes. + + aes_08t (an unsigned 8-bit type) + aes_32t (an unsigned 32-bit type) + struct aes_encrypt_ctx (structure for the cipher encryption context) + struct aes_decrypt_ctx (structure for the cipher decryption context) + aes_rval the function return type + + C subroutine calls: + + aes_rval aes_encrypt_key128(const unsigned char *key, aes_encrypt_ctx cx[1]); + aes_rval aes_encrypt_key192(const unsigned char *key, aes_encrypt_ctx cx[1]); + aes_rval aes_encrypt_key256(const unsigned char *key, aes_encrypt_ctx cx[1]); + aes_rval aes_encrypt(const unsigned char *in, unsigned char *out, + const aes_encrypt_ctx cx[1]); + + aes_rval aes_decrypt_key128(const unsigned char *key, aes_decrypt_ctx cx[1]); + aes_rval aes_decrypt_key192(const unsigned char *key, aes_decrypt_ctx cx[1]); + aes_rval aes_decrypt_key256(const unsigned char *key, aes_decrypt_ctx cx[1]); + aes_rval aes_decrypt(const unsigned char *in, unsigned char *out, + const aes_decrypt_ctx cx[1]); + + IMPORTANT NOTE: If you are using this C interface with dynamic tables make sure that + you call genTabs() before AES is used so that the tables are initialised. + + C++ aes class subroutines: + + Class AESencrypt for encryption + + Construtors: + AESencrypt(void) + AESencrypt(const unsigned char *key) - 128 bit key + Members: + aes_rval key128(const unsigned char *key) + aes_rval key192(const unsigned char *key) + aes_rval key256(const unsigned char *key) + aes_rval encrypt(const unsigned char *in, unsigned char *out) const + + Class AESdecrypt for encryption + Construtors: + AESdecrypt(void) + AESdecrypt(const unsigned char *key) - 128 bit key + Members: + aes_rval key128(const unsigned char *key) + aes_rval key192(const unsigned char *key) + aes_rval key256(const unsigned char *key) + aes_rval decrypt(const unsigned char *in, unsigned char *out) const + + COMPILATION + + The files used to provide AES (Rijndael) are + + a. aes.h for the definitions needed for use in C. + b. aescpp.h for the definitions needed for use in C++. + c. aesopt.h for setting compilation options (also includes common code). + d. aescrypt.c for encryption and decrytpion, or + e. aeskey.c for key scheduling. + f. aestab.c for table loading or generation. + g. aescrypt.asm for encryption and decryption using assembler code. + h. aescrypt.mmx.asm for encryption and decryption using MMX assembler. + + To compile AES (Rijndael) for use in C code use aes.h and set the + defines here for the facilities you need (key lengths, encryption + and/or decryption). Do not define AES_DLL or AES_CPP. Set the options + for optimisations and table sizes here. + + To compile AES (Rijndael) for use in in C++ code use aescpp.h but do + not define AES_DLL + + To compile AES (Rijndael) in C as a Dynamic Link Library DLL) use + aes.h and include the AES_DLL define. + + CONFIGURATION OPTIONS (here and in aes.h) + + a. set AES_DLL in aes.h if AES (Rijndael) is to be compiled as a DLL + b. You may need to set PLATFORM_BYTE_ORDER to define the byte order. + c. If you want the code to run in a specific internal byte order, then + ALGORITHM_BYTE_ORDER must be set accordingly. + d. set other configuration options decribed below. +*/ + +#if !defined( _AESOPT_H ) +#define _AESOPT_H + +#include "aes.h" + +/* CONFIGURATION - USE OF DEFINES + + Later in this section there are a number of defines that control the + operation of the code. In each section, the purpose of each define is + explained so that the relevant form can be included or excluded by + setting either 1's or 0's respectively on the branches of the related + #if clauses. + + PLATFORM SPECIFIC INCLUDES AND BYTE ORDER IN 32-BIT WORDS + + To obtain the highest speed on processors with 32-bit words, this code + needs to determine the byte order of the target machine. The following + block of code is an attempt to capture the most obvious ways in which + various environemnts define byte order. It may well fail, in which case + the definitions will need to be set by editing at the points marked + **** EDIT HERE IF NECESSARY **** below. My thanks go to Peter Gutmann + for his assistance with this endian detection nightmare. +*/ + +#define BRG_LITTLE_ENDIAN 1234 /* byte 0 is least significant (i386) */ +#define BRG_BIG_ENDIAN 4321 /* byte 0 is most significant (mc68k) */ + +#if defined(__GNUC__) || defined(__GNU_LIBRARY__) +# if defined(__FreeBSD__) || defined(__OpenBSD__) +# include <sys/endian.h> +# elif defined( BSD ) && BSD >= 199103 +# include <machine/endian.h> +# elif defined(__APPLE__) +# if defined(__BIG_ENDIAN__) && !defined( BIG_ENDIAN ) +# define BIG_ENDIAN +# elif defined(__LITTLE_ENDIAN__) && !defined( LITTLE_ENDIAN ) +# define LITTLE_ENDIAN +# endif +# else +# include <endian.h> +# if defined(__BEOS__) +# include <byteswap.h> +# endif +# endif +#endif + +#if !defined(PLATFORM_BYTE_ORDER) +# if defined(LITTLE_ENDIAN) || defined(BIG_ENDIAN) +# if defined(LITTLE_ENDIAN) && !defined(BIG_ENDIAN) +# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN +# elif !defined(LITTLE_ENDIAN) && defined(BIG_ENDIAN) +# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN +# elif defined(BYTE_ORDER) && (BYTE_ORDER == LITTLE_ENDIAN) +# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN +# elif defined(BYTE_ORDER) && (BYTE_ORDER == BIG_ENDIAN) +# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN +# endif +# elif defined(_LITTLE_ENDIAN) || defined(_BIG_ENDIAN) +# if defined(_LITTLE_ENDIAN) && !defined(_BIG_ENDIAN) +# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN +# elif !defined(_LITTLE_ENDIAN) && defined(_BIG_ENDIAN) +# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN +# elif defined(_BYTE_ORDER) && (_BYTE_ORDER == _LITTLE_ENDIAN) +# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN +# elif defined(_BYTE_ORDER) && (_BYTE_ORDER == _BIG_ENDIAN) +# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN +# endif +# elif defined(__LITTLE_ENDIAN__) || defined(__BIG_ENDIAN__) +# if defined(__LITTLE_ENDIAN__) && !defined(__BIG_ENDIAN__) +# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN +# elif !defined(__LITTLE_ENDIAN__) && defined(__BIG_ENDIAN__) +# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN +# elif defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __LITTLE_ENDIAN__) +# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN +# elif defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __BIG_ENDIAN__) +# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN +# endif +# endif +#endif + +/* if the platform is still unknown, try to find its byte order */ +/* from commonly used machine defines */ + +#if !defined(PLATFORM_BYTE_ORDER) + +#if defined( __alpha__ ) || defined( __alpha ) || defined( i386 ) || \ + defined( __i386__ ) || defined( _M_I86 ) || defined( _M_IX86 ) || \ + defined( __OS2__ ) || defined( sun386 ) || defined( __TURBOC__ ) || \ + defined( vax ) || defined( vms ) || defined( VMS ) || \ + defined( __VMS ) +# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN + +#elif defined( AMIGA ) || defined( applec ) || defined( __AS400__ ) || \ + defined( _CRAY ) || defined( __hppa ) || defined( __hp9000 ) || \ + defined( ibm370 ) || defined( mc68000 ) || defined( m68k ) || \ + defined( __MRC__ ) || defined( __MVS__ ) || defined( __MWERKS__ ) || \ + defined( sparc ) || defined( __sparc) || defined( SYMANTEC_C ) || \ + defined( __TANDEM ) || defined( THINK_C ) || defined( __VMCMS__ ) +# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN + +#elif 0 /* **** EDIT HERE IF NECESSARY **** */ +# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN +#elif 0 /* **** EDIT HERE IF NECESSARY **** */ +# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN +#else +# error Please edit aesopt.h (line 234 or 236) to set the platform byte order +#endif + +#endif + +/* SOME LOCAL DEFINITIONS */ + +#define NO_TABLES 0 +#define ONE_TABLE 1 +#define FOUR_TABLES 4 +#define NONE 0 +#define PARTIAL 1 +#define FULL 2 + +#if defined(bswap32) +#define aes_sw32 bswap32 +#elif defined(bswap_32) +#define aes_sw32 bswap_32 +#else +#define brot(x,n) (((aes_32t)(x) << n) | ((aes_32t)(x) >> (32 - n))) +#define aes_sw32(x) ((brot((x),8) & 0x00ff00ff) | (brot((x),24) & 0xff00ff00)) +#endif + +/* 1. FUNCTIONS REQUIRED + + This implementation provides subroutines for encryption, decryption + and for setting the three key lengths (separately) for encryption + and decryption. When the assembler code is not being used the following + definition blocks allow the selection of the routines that are to be + included in the compilation. +*/ +#if defined( AES_ENCRYPT ) +#define ENCRYPTION +#define ENCRYPTION_KEY_SCHEDULE +#endif + +#if defined( AES_DECRYPT ) +#define DECRYPTION +#define DECRYPTION_KEY_SCHEDULE +#endif + +/* 2. ASSEMBLER SUPPORT + + This define (which can be on the command line) enables the use of the + assembler code routines for encryption and decryption with the C code + only providing key scheduling +*/ +#if 0 && !defined(AES_ASM) +#define AES_ASM +#endif + +/* 3. BYTE ORDER WITHIN 32 BIT WORDS + + The fundamental data processing units in Rijndael are 8-bit bytes. The + input, output and key input are all enumerated arrays of bytes in which + bytes are numbered starting at zero and increasing to one less than the + number of bytes in the array in question. This enumeration is only used + for naming bytes and does not imply any adjacency or order relationship + from one byte to another. When these inputs and outputs are considered + as bit sequences, bits 8*n to 8*n+7 of the bit sequence are mapped to + byte[n] with bit 8n+i in the sequence mapped to bit 7-i within the byte. + In this implementation bits are numbered from 0 to 7 starting at the + numerically least significant end of each byte (bit n represents 2^n). + + However, Rijndael can be implemented more efficiently using 32-bit + words by packing bytes into words so that bytes 4*n to 4*n+3 are placed + into word[n]. While in principle these bytes can be assembled into words + in any positions, this implementation only supports the two formats in + which bytes in adjacent positions within words also have adjacent byte + numbers. This order is called big-endian if the lowest numbered bytes + in words have the highest numeric significance and little-endian if the + opposite applies. + + This code can work in either order irrespective of the order used by the + machine on which it runs. Normally the internal byte order will be set + to the order of the processor on which the code is to be run but this + define can be used to reverse this in special situations + + NOTE: Assembler code versions rely on PLATFORM_BYTE_ORDER being set +*/ +#if 1 || defined(AES_ASM) +#define ALGORITHM_BYTE_ORDER PLATFORM_BYTE_ORDER +#elif 0 +#define ALGORITHM_BYTE_ORDER BRG_LITTLE_ENDIAN +#elif 0 +#define ALGORITHM_BYTE_ORDER BRG_BIG_ENDIAN +#else +#error The algorithm byte order is not defined +#endif + +/* 4. FAST INPUT/OUTPUT OPERATIONS. + + On some machines it is possible to improve speed by transferring the + bytes in the input and output arrays to and from the internal 32-bit + variables by addressing these arrays as if they are arrays of 32-bit + words. On some machines this will always be possible but there may + be a large performance penalty if the byte arrays are not aligned on + the normal word boundaries. On other machines this technique will + lead to memory access errors when such 32-bit word accesses are not + properly aligned. The option SAFE_IO avoids such problems but will + often be slower on those machines that support misaligned access + (especially so if care is taken to align the input and output byte + arrays on 32-bit word boundaries). If SAFE_IO is not defined it is + assumed that access to byte arrays as if they are arrays of 32-bit + words will not cause problems when such accesses are misaligned. +*/ +#if 0 && !defined(_MSC_VER) +#define SAFE_IO +#endif + +/* 5. LOOP UNROLLING + + The code for encryption and decrytpion cycles through a number of rounds + that can be implemented either in a loop or by expanding the code into a + long sequence of instructions, the latter producing a larger program but + one that will often be much faster. The latter is called loop unrolling. + There are also potential speed advantages in expanding two iterations in + a loop with half the number of iterations, which is called partial loop + unrolling. The following options allow partial or full loop unrolling + to be set independently for encryption and decryption +*/ +#if 1 +#define ENC_UNROLL FULL +#elif 0 +#define ENC_UNROLL PARTIAL +#else +#define ENC_UNROLL NONE +#endif + +#if 1 +#define DEC_UNROLL FULL +#elif 0 +#define DEC_UNROLL PARTIAL +#else +#define DEC_UNROLL NONE +#endif + +/* 6. FAST FINITE FIELD OPERATIONS + + If this section is included, tables are used to provide faster finite + field arithmetic (this has no effect if FIXED_TABLES is defined). +*/ +#if 1 +#define FF_TABLES +#endif + +/* 7. INTERNAL STATE VARIABLE FORMAT + + The internal state of Rijndael is stored in a number of local 32-bit + word varaibles which can be defined either as an array or as individual + names variables. Include this section if you want to store these local + varaibles in arrays. Otherwise individual local variables will be used. +*/ +#if 0 +#define ARRAYS +#endif + +/* In this implementation the columns of the state array are each held in + 32-bit words. The state array can be held in various ways: in an array + of words, in a number of individual word variables or in a number of + processor registers. The following define maps a variable name x and + a column number c to the way the state array variable is to be held. + The first define below maps the state into an array x[c] whereas the + second form maps the state into a number of individual variables x0, + x1, etc. Another form could map individual state colums to machine + register names. +*/ + +#if defined(ARRAYS) +#define s(x,c) x[c] +#else +#define s(x,c) x##c +#endif + +/* 8. FIXED OR DYNAMIC TABLES + + When this section is included the tables used by the code are compiled + statically into the binary file. Otherwise the subroutine gen_tabs() + must be called to compute them before the code is first used. +*/ +#if 1 +#define FIXED_TABLES +#endif + +/* 9. TABLE ALIGNMENT + + On some sytsems speed will be improved by aligning the AES large lookup + tables on particular boundaries. This define should be set to a power of + two giving the desired alignment. It can be left undefined if alignment + is not needed. This option is specific to the Microsft VC++ compiler - + it seems to sometimes cause trouble for the VC++ version 6 compiler. +*/ + +#if 0 && defined(_MSC_VER) && (_MSC_VER >= 1300) +#define TABLE_ALIGN 64 +#endif + +/* 10. INTERNAL TABLE CONFIGURATION + + This cipher proceeds by repeating in a number of cycles known as 'rounds' + which are implemented by a round function which can optionally be speeded + up using tables. The basic tables are each 256 32-bit words, with either + one or four tables being required for each round function depending on + how much speed is required. The encryption and decryption round functions + are different and the last encryption and decrytpion round functions are + different again making four different round functions in all. + + This means that: + 1. Normal encryption and decryption rounds can each use either 0, 1 + or 4 tables and table spaces of 0, 1024 or 4096 bytes each. + 2. The last encryption and decryption rounds can also use either 0, 1 + or 4 tables and table spaces of 0, 1024 or 4096 bytes each. + + Include or exclude the appropriate definitions below to set the number + of tables used by this implementation. +*/ + +#if 1 /* set tables for the normal encryption round */ +#define ENC_ROUND FOUR_TABLES +#elif 0 +#define ENC_ROUND ONE_TABLE +#else +#define ENC_ROUND NO_TABLES +#endif + +#if 1 /* set tables for the last encryption round */ +#define LAST_ENC_ROUND FOUR_TABLES +#elif 0 +#define LAST_ENC_ROUND ONE_TABLE +#else +#define LAST_ENC_ROUND NO_TABLES +#endif + +#if 1 /* set tables for the normal decryption round */ +#define DEC_ROUND FOUR_TABLES +#elif 0 +#define DEC_ROUND ONE_TABLE +#else +#define DEC_ROUND NO_TABLES +#endif + +#if 1 /* set tables for the last decryption round */ +#define LAST_DEC_ROUND FOUR_TABLES +#elif 0 +#define LAST_DEC_ROUND ONE_TABLE +#else +#define LAST_DEC_ROUND NO_TABLES +#endif + +/* The decryption key schedule can be speeded up with tables in the same + way that the round functions can. Include or exclude the following + defines to set this requirement. +*/ +#if 1 +#define KEY_SCHED FOUR_TABLES +#elif 0 +#define KEY_SCHED ONE_TABLE +#else +#define KEY_SCHED NO_TABLES +#endif + +/* 11. TABLE POINTER CACHING + + Normally tables are referenced directly, Enable this option if you wish to + cache pointers to the tables in the encrypt/decrypt code. Note that this + only works if you are using FOUR_TABLES for the ROUND you enable this for. +*/ +#if 1 +#define ENC_ROUND_CACHE_TABLES +#endif +#if 1 +#define LAST_ENC_ROUND_CACHE_TABLES +#endif +#if 1 +#define DEC_ROUND_CACHE_TABLES +#endif +#if 1 +#define LAST_DEC_ROUND_CACHE_TABLES +#endif + + +/* END OF CONFIGURATION OPTIONS */ + +#define RC_LENGTH (5 * (AES_BLOCK_SIZE / 4 - 2)) + +/* Disable or report errors on some combinations of options */ + +#if ENC_ROUND == NO_TABLES && LAST_ENC_ROUND != NO_TABLES +#undef LAST_ENC_ROUND +#define LAST_ENC_ROUND NO_TABLES +#elif ENC_ROUND == ONE_TABLE && LAST_ENC_ROUND == FOUR_TABLES +#undef LAST_ENC_ROUND +#define LAST_ENC_ROUND ONE_TABLE +#endif + +#if ENC_ROUND == NO_TABLES && ENC_UNROLL != NONE +#undef ENC_UNROLL +#define ENC_UNROLL NONE +#endif + +#if DEC_ROUND == NO_TABLES && LAST_DEC_ROUND != NO_TABLES +#undef LAST_DEC_ROUND +#define LAST_DEC_ROUND NO_TABLES +#elif DEC_ROUND == ONE_TABLE && LAST_DEC_ROUND == FOUR_TABLES +#undef LAST_DEC_ROUND +#define LAST_DEC_ROUND ONE_TABLE +#endif + +#if DEC_ROUND == NO_TABLES && DEC_UNROLL != NONE +#undef DEC_UNROLL +#define DEC_UNROLL NONE +#endif + +/* upr(x,n): rotates bytes within words by n positions, moving bytes to + higher index positions with wrap around into low positions + ups(x,n): moves bytes by n positions to higher index positions in + words but without wrap around + bval(x,n): extracts a byte from a word + + NOTE: The definitions given here are intended only for use with + unsigned variables and with shift counts that are compile + time constants +*/ + +#if (ALGORITHM_BYTE_ORDER == BRG_LITTLE_ENDIAN) +#define upr(x,n) (((aes_32t)(x) << (8 * (n))) | ((aes_32t)(x) >> (32 - 8 * (n)))) +#define ups(x,n) ((aes_32t) (x) << (8 * (n))) +#define bval(x,n) ((aes_08t)((x) >> (8 * (n)))) +#define bytes2word(b0, b1, b2, b3) \ + (((aes_32t)(b3) << 24) | ((aes_32t)(b2) << 16) | ((aes_32t)(b1) << 8) | (b0)) +#endif + +#if (ALGORITHM_BYTE_ORDER == BRG_BIG_ENDIAN) +#define upr(x,n) (((aes_32t)(x) >> (8 * (n))) | ((aes_32t)(x) << (32 - 8 * (n)))) +#define ups(x,n) ((aes_32t) (x) >> (8 * (n)))) +#define bval(x,n) ((aes_08t)((x) >> (24 - 8 * (n)))) +#define bytes2word(b0, b1, b2, b3) \ + (((aes_32t)(b0) << 24) | ((aes_32t)(b1) << 16) | ((aes_32t)(b2) << 8) | (b3)) +#endif + +#if defined(SAFE_IO) + +#define word_in(x,c) bytes2word(((aes_08t*)(x)+4*c)[0], ((aes_08t*)(x)+4*c)[1], \ + ((aes_08t*)(x)+4*c)[2], ((aes_08t*)(x)+4*c)[3]) +#define word_out(x,c,v) { ((aes_08t*)(x)+4*c)[0] = bval(v,0); ((aes_08t*)(x)+4*c)[1] = bval(v,1); \ + ((aes_08t*)(x)+4*c)[2] = bval(v,2); ((aes_08t*)(x)+4*c)[3] = bval(v,3); } + +#elif (ALGORITHM_BYTE_ORDER == PLATFORM_BYTE_ORDER) + +#define word_in(x,c) (*((aes_32t*)(x)+(c))) +#define word_out(x,c,v) (*((aes_32t*)(x)+(c)) = (v)) + +#else + +#define word_in(x,c) aes_sw32(*((aes_32t*)(x)+(c))) +#define word_out(x,c,v) (*((aes_32t*)(x)+(c)) = aes_sw32(v)) + +#endif + +/* the finite field modular polynomial and elements */ + +#define WPOLY 0x011b +#define BPOLY 0x1b + +/* multiply four bytes in GF(2^8) by 'x' {02} in parallel */ + +#define m1 0x80808080 +#define m2 0x7f7f7f7f +#define gf_mulx(x) ((((x) & m2) << 1) ^ ((((x) & m1) >> 7) * BPOLY)) + +/* The following defines provide alternative definitions of gf_mulx that might + give improved performance if a fast 32-bit multiply is not available. Note + that a temporary variable u needs to be defined where gf_mulx is used. + +#define gf_mulx(x) (u = (x) & m1, u |= (u >> 1), ((x) & m2) << 1) ^ ((u >> 3) | (u >> 6)) +#define m4 (0x01010101 * BPOLY) +#define gf_mulx(x) (u = (x) & m1, ((x) & m2) << 1) ^ ((u - (u >> 7)) & m4) +*/ + +/* Work out which tables are needed for the different options */ + +#if defined( AES_ASM ) +#if defined( ENC_ROUND ) +#undef ENC_ROUND +#endif +#define ENC_ROUND FOUR_TABLES +#if defined( LAST_ENC_ROUND ) +#undef LAST_ENC_ROUND +#endif +#define LAST_ENC_ROUND FOUR_TABLES +#if defined( DEC_ROUND ) +#undef DEC_ROUND +#endif +#define DEC_ROUND FOUR_TABLES +#if defined( LAST_DEC_ROUND ) +#undef LAST_DEC_ROUND +#endif +#define LAST_DEC_ROUND FOUR_TABLES +#if defined( KEY_SCHED ) +#undef KEY_SCHED +#define KEY_SCHED FOUR_TABLES +#endif +#endif + +#if defined(ENCRYPTION) || defined(AES_ASM) +#if ENC_ROUND == ONE_TABLE +#define FT1_SET +#elif ENC_ROUND == FOUR_TABLES +#define FT4_SET +#else +#define SBX_SET +#endif +#if LAST_ENC_ROUND == ONE_TABLE +#define FL1_SET +#elif LAST_ENC_ROUND == FOUR_TABLES +#define FL4_SET +#elif !defined(SBX_SET) +#define SBX_SET +#endif +#endif + +#if defined(DECRYPTION) || defined(AES_ASM) +#if DEC_ROUND == ONE_TABLE +#define IT1_SET +#elif DEC_ROUND == FOUR_TABLES +#define IT4_SET +#else +#define ISB_SET +#endif +#if LAST_DEC_ROUND == ONE_TABLE +#define IL1_SET +#elif LAST_DEC_ROUND == FOUR_TABLES +#define IL4_SET +#elif !defined(ISB_SET) +#define ISB_SET +#endif +#endif + +#if defined(ENCRYPTION_KEY_SCHEDULE) || defined(DECRYPTION_KEY_SCHEDULE) +#if KEY_SCHED == ONE_TABLE +#define LS1_SET +#define IM1_SET +#elif KEY_SCHED == FOUR_TABLES +#define LS4_SET +#define IM4_SET +#elif !defined(SBX_SET) +#define SBX_SET +#endif +#endif + +/* generic definitions of Rijndael macros that use tables */ + +#define no_table(x,box,vf,rf,c) bytes2word( \ + box[bval(vf(x,0,c),rf(0,c))], \ + box[bval(vf(x,1,c),rf(1,c))], \ + box[bval(vf(x,2,c),rf(2,c))], \ + box[bval(vf(x,3,c),rf(3,c))]) + +#define one_table(x,op,tab,vf,rf,c) \ + ( tab[bval(vf(x,0,c),rf(0,c))] \ + ^ op(tab[bval(vf(x,1,c),rf(1,c))],1) \ + ^ op(tab[bval(vf(x,2,c),rf(2,c))],2) \ + ^ op(tab[bval(vf(x,3,c),rf(3,c))],3)) + +#define four_tables(x,tab,vf,rf,c) \ + ( tab[0][bval(vf(x,0,c),rf(0,c))] \ + ^ tab[1][bval(vf(x,1,c),rf(1,c))] \ + ^ tab[2][bval(vf(x,2,c),rf(2,c))] \ + ^ tab[3][bval(vf(x,3,c),rf(3,c))]) + +#define four_cached_tables(x,tab,vf,rf,c) \ +( tab##0[bval(vf(x,0,c),rf(0,c))] \ + ^ tab##1[bval(vf(x,1,c),rf(1,c))] \ + ^ tab##2[bval(vf(x,2,c),rf(2,c))] \ + ^ tab##3[bval(vf(x,3,c),rf(3,c))]) + +#define vf1(x,r,c) (x) +#define rf1(r,c) (r) +#define rf2(r,c) ((8+r-c)&3) + +/* perform forward and inverse column mix operation on four bytes in long word x in */ +/* parallel. NOTE: x must be a simple variable, NOT an expression in these macros. */ + +#if defined(FM4_SET) /* not currently used */ +#define fwd_mcol(x) four_tables(x,t_use(f,m),vf1,rf1,0) +#elif defined(FM1_SET) /* not currently used */ +#define fwd_mcol(x) one_table(x,upr,t_use(f,m),vf1,rf1,0) +#else +#define dec_fmvars aes_32t g2 +#define fwd_mcol(x) (g2 = gf_mulx(x), g2 ^ upr((x) ^ g2, 3) ^ upr((x), 2) ^ upr((x), 1)) +#endif + +#if defined(IM4_SET) +#define inv_mcol(x) four_tables(x,t_use(i,m),vf1,rf1,0) +#elif defined(IM1_SET) +#define inv_mcol(x) one_table(x,upr,t_use(i,m),vf1,rf1,0) +#else +#define dec_imvars aes_32t g2, g4, g9 +#define inv_mcol(x) (g2 = gf_mulx(x), g4 = gf_mulx(g2), g9 = (x) ^ gf_mulx(g4), g4 ^= g9, \ + (x) ^ g2 ^ g4 ^ upr(g2 ^ g9, 3) ^ upr(g4, 2) ^ upr(g9, 1)) +#endif + +#if defined(FL4_SET) +#define ls_box(x,c) four_tables(x,t_use(f,l),vf1,rf2,c) +#elif defined(LS4_SET) +#define ls_box(x,c) four_tables(x,t_use(l,s),vf1,rf2,c) +#elif defined(FL1_SET) +#define ls_box(x,c) one_table(x,upr,t_use(f,l),vf1,rf2,c) +#elif defined(LS1_SET) +#define ls_box(x,c) one_table(x,upr,t_use(l,s),vf1,rf2,c) +#else +#define ls_box(x,c) no_table(x,t_use(s,box),vf1,rf2,c) +#endif + +#endif diff --git a/bsd/crypto/aes/aestab.c b/bsd/crypto/aes/aestab.c index 7997f2978..dfd2ee969 100644 --- a/bsd/crypto/aes/aestab.c +++ b/bsd/crypto/aes/aestab.c @@ -1,384 +1,384 @@ -/* - --------------------------------------------------------------------------- - Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. - - LICENSE TERMS - - The free distribution and use of this software in both source and binary - form is allowed (with or without changes) provided that: - - 1. distributions of this source code include the above copyright - notice, this list of conditions and the following disclaimer; - - 2. distributions in binary form include the above copyright - notice, this list of conditions and the following disclaimer - in the documentation and/or other associated materials; - - 3. the copyright holder's name is not used to endorse products - built using this software without specific written permission. - - ALTERNATIVELY, provided that this notice is retained in full, this product - may be distributed under the terms of the GNU General Public License (GPL), - in which case the provisions of the GPL apply INSTEAD OF those given above. - - DISCLAIMER - - This software is provided 'as is' with no explicit or implied warranties - in respect of its properties, including, but not limited to, correctness - and/or fitness for purpose. - --------------------------------------------------------------------------- - Issue 28/01/2004 - -*/ - -#if defined(__cplusplus) -extern "C" -{ -#endif - -#define DO_TABLES - -#include "aesopt.h" - -#if defined(FIXED_TABLES) - -#define sb_data(w) {\ - w(0x63), w(0x7c), w(0x77), w(0x7b), w(0xf2), w(0x6b), w(0x6f), w(0xc5),\ - w(0x30), w(0x01), w(0x67), w(0x2b), w(0xfe), w(0xd7), w(0xab), w(0x76),\ - w(0xca), w(0x82), w(0xc9), w(0x7d), w(0xfa), w(0x59), w(0x47), w(0xf0),\ - w(0xad), w(0xd4), w(0xa2), w(0xaf), w(0x9c), w(0xa4), w(0x72), w(0xc0),\ - w(0xb7), w(0xfd), w(0x93), w(0x26), w(0x36), w(0x3f), w(0xf7), w(0xcc),\ - w(0x34), w(0xa5), w(0xe5), w(0xf1), w(0x71), w(0xd8), w(0x31), w(0x15),\ - w(0x04), w(0xc7), w(0x23), w(0xc3), w(0x18), w(0x96), w(0x05), w(0x9a),\ - w(0x07), w(0x12), w(0x80), w(0xe2), w(0xeb), w(0x27), w(0xb2), w(0x75),\ - w(0x09), w(0x83), w(0x2c), w(0x1a), w(0x1b), w(0x6e), w(0x5a), w(0xa0),\ - w(0x52), w(0x3b), w(0xd6), w(0xb3), w(0x29), w(0xe3), w(0x2f), w(0x84),\ - w(0x53), w(0xd1), w(0x00), w(0xed), w(0x20), w(0xfc), w(0xb1), w(0x5b),\ - w(0x6a), w(0xcb), w(0xbe), w(0x39), w(0x4a), w(0x4c), w(0x58), w(0xcf),\ - w(0xd0), w(0xef), w(0xaa), w(0xfb), w(0x43), w(0x4d), w(0x33), w(0x85),\ - w(0x45), w(0xf9), w(0x02), w(0x7f), w(0x50), w(0x3c), w(0x9f), w(0xa8),\ - w(0x51), w(0xa3), w(0x40), w(0x8f), w(0x92), w(0x9d), w(0x38), w(0xf5),\ - w(0xbc), w(0xb6), w(0xda), w(0x21), w(0x10), w(0xff), w(0xf3), w(0xd2),\ - w(0xcd), w(0x0c), w(0x13), w(0xec), w(0x5f), w(0x97), w(0x44), w(0x17),\ - w(0xc4), w(0xa7), w(0x7e), w(0x3d), w(0x64), w(0x5d), w(0x19), w(0x73),\ - w(0x60), w(0x81), w(0x4f), w(0xdc), w(0x22), w(0x2a), w(0x90), w(0x88),\ - w(0x46), w(0xee), w(0xb8), w(0x14), w(0xde), w(0x5e), w(0x0b), w(0xdb),\ - w(0xe0), w(0x32), w(0x3a), w(0x0a), w(0x49), w(0x06), w(0x24), w(0x5c),\ - w(0xc2), w(0xd3), w(0xac), w(0x62), w(0x91), w(0x95), w(0xe4), w(0x79),\ - w(0xe7), w(0xc8), w(0x37), w(0x6d), w(0x8d), w(0xd5), w(0x4e), w(0xa9),\ - w(0x6c), w(0x56), w(0xf4), w(0xea), w(0x65), w(0x7a), w(0xae), w(0x08),\ - w(0xba), w(0x78), w(0x25), w(0x2e), w(0x1c), w(0xa6), w(0xb4), w(0xc6),\ - w(0xe8), w(0xdd), w(0x74), w(0x1f), w(0x4b), w(0xbd), w(0x8b), w(0x8a),\ - w(0x70), w(0x3e), w(0xb5), w(0x66), w(0x48), w(0x03), w(0xf6), w(0x0e),\ - w(0x61), w(0x35), w(0x57), w(0xb9), w(0x86), w(0xc1), w(0x1d), w(0x9e),\ - w(0xe1), w(0xf8), w(0x98), w(0x11), w(0x69), w(0xd9), w(0x8e), w(0x94),\ - w(0x9b), w(0x1e), w(0x87), w(0xe9), w(0xce), w(0x55), w(0x28), w(0xdf),\ - w(0x8c), w(0xa1), w(0x89), w(0x0d), w(0xbf), w(0xe6), w(0x42), w(0x68),\ - w(0x41), w(0x99), w(0x2d), w(0x0f), w(0xb0), w(0x54), w(0xbb), w(0x16) } - -#define isb_data(w) {\ - w(0x52), w(0x09), w(0x6a), w(0xd5), w(0x30), w(0x36), w(0xa5), w(0x38),\ - w(0xbf), w(0x40), w(0xa3), w(0x9e), w(0x81), w(0xf3), w(0xd7), w(0xfb),\ - w(0x7c), w(0xe3), w(0x39), w(0x82), w(0x9b), w(0x2f), w(0xff), w(0x87),\ - w(0x34), w(0x8e), w(0x43), w(0x44), w(0xc4), w(0xde), w(0xe9), w(0xcb),\ - w(0x54), w(0x7b), w(0x94), w(0x32), w(0xa6), w(0xc2), w(0x23), w(0x3d),\ - w(0xee), w(0x4c), w(0x95), w(0x0b), w(0x42), w(0xfa), w(0xc3), w(0x4e),\ - w(0x08), w(0x2e), w(0xa1), w(0x66), w(0x28), w(0xd9), w(0x24), w(0xb2),\ - w(0x76), w(0x5b), w(0xa2), w(0x49), w(0x6d), w(0x8b), w(0xd1), w(0x25),\ - w(0x72), w(0xf8), w(0xf6), w(0x64), w(0x86), w(0x68), w(0x98), w(0x16),\ - w(0xd4), w(0xa4), w(0x5c), w(0xcc), w(0x5d), w(0x65), w(0xb6), w(0x92),\ - w(0x6c), w(0x70), w(0x48), w(0x50), w(0xfd), w(0xed), w(0xb9), w(0xda),\ - w(0x5e), w(0x15), w(0x46), w(0x57), w(0xa7), w(0x8d), w(0x9d), w(0x84),\ - w(0x90), w(0xd8), w(0xab), w(0x00), w(0x8c), w(0xbc), w(0xd3), w(0x0a),\ - w(0xf7), w(0xe4), w(0x58), w(0x05), w(0xb8), w(0xb3), w(0x45), w(0x06),\ - w(0xd0), w(0x2c), w(0x1e), w(0x8f), w(0xca), w(0x3f), w(0x0f), w(0x02),\ - w(0xc1), w(0xaf), w(0xbd), w(0x03), w(0x01), w(0x13), w(0x8a), w(0x6b),\ - w(0x3a), w(0x91), w(0x11), w(0x41), w(0x4f), w(0x67), w(0xdc), w(0xea),\ - w(0x97), w(0xf2), w(0xcf), w(0xce), w(0xf0), w(0xb4), w(0xe6), w(0x73),\ - w(0x96), w(0xac), w(0x74), w(0x22), w(0xe7), w(0xad), w(0x35), w(0x85),\ - w(0xe2), w(0xf9), w(0x37), w(0xe8), w(0x1c), w(0x75), w(0xdf), w(0x6e),\ - w(0x47), w(0xf1), w(0x1a), w(0x71), w(0x1d), w(0x29), w(0xc5), w(0x89),\ - w(0x6f), w(0xb7), w(0x62), w(0x0e), w(0xaa), w(0x18), w(0xbe), w(0x1b),\ - w(0xfc), w(0x56), w(0x3e), w(0x4b), w(0xc6), w(0xd2), w(0x79), w(0x20),\ - w(0x9a), w(0xdb), w(0xc0), w(0xfe), w(0x78), w(0xcd), w(0x5a), w(0xf4),\ - w(0x1f), w(0xdd), w(0xa8), w(0x33), w(0x88), w(0x07), w(0xc7), w(0x31),\ - w(0xb1), w(0x12), w(0x10), w(0x59), w(0x27), w(0x80), w(0xec), w(0x5f),\ - w(0x60), w(0x51), w(0x7f), w(0xa9), w(0x19), w(0xb5), w(0x4a), w(0x0d),\ - w(0x2d), w(0xe5), w(0x7a), w(0x9f), w(0x93), w(0xc9), w(0x9c), w(0xef),\ - w(0xa0), w(0xe0), w(0x3b), w(0x4d), w(0xae), w(0x2a), w(0xf5), w(0xb0),\ - w(0xc8), w(0xeb), w(0xbb), w(0x3c), w(0x83), w(0x53), w(0x99), w(0x61),\ - w(0x17), w(0x2b), w(0x04), w(0x7e), w(0xba), w(0x77), w(0xd6), w(0x26),\ - w(0xe1), w(0x69), w(0x14), w(0x63), w(0x55), w(0x21), w(0x0c), w(0x7d) } - -#define mm_data(w) {\ - w(0x00), w(0x01), w(0x02), w(0x03), w(0x04), w(0x05), w(0x06), w(0x07),\ - w(0x08), w(0x09), w(0x0a), w(0x0b), w(0x0c), w(0x0d), w(0x0e), w(0x0f),\ - w(0x10), w(0x11), w(0x12), w(0x13), w(0x14), w(0x15), w(0x16), w(0x17),\ - w(0x18), w(0x19), w(0x1a), w(0x1b), w(0x1c), w(0x1d), w(0x1e), w(0x1f),\ - w(0x20), w(0x21), w(0x22), w(0x23), w(0x24), w(0x25), w(0x26), w(0x27),\ - w(0x28), w(0x29), w(0x2a), w(0x2b), w(0x2c), w(0x2d), w(0x2e), w(0x2f),\ - w(0x30), w(0x31), w(0x32), w(0x33), w(0x34), w(0x35), w(0x36), w(0x37),\ - w(0x38), w(0x39), w(0x3a), w(0x3b), w(0x3c), w(0x3d), w(0x3e), w(0x3f),\ - w(0x40), w(0x41), w(0x42), w(0x43), w(0x44), w(0x45), w(0x46), w(0x47),\ - w(0x48), w(0x49), w(0x4a), w(0x4b), w(0x4c), w(0x4d), w(0x4e), w(0x4f),\ - w(0x50), w(0x51), w(0x52), w(0x53), w(0x54), w(0x55), w(0x56), w(0x57),\ - w(0x58), w(0x59), w(0x5a), w(0x5b), w(0x5c), w(0x5d), w(0x5e), w(0x5f),\ - w(0x60), w(0x61), w(0x62), w(0x63), w(0x64), w(0x65), w(0x66), w(0x67),\ - w(0x68), w(0x69), w(0x6a), w(0x6b), w(0x6c), w(0x6d), w(0x6e), w(0x6f),\ - w(0x70), w(0x71), w(0x72), w(0x73), w(0x74), w(0x75), w(0x76), w(0x77),\ - w(0x78), w(0x79), w(0x7a), w(0x7b), w(0x7c), w(0x7d), w(0x7e), w(0x7f),\ - w(0x80), w(0x81), w(0x82), w(0x83), w(0x84), w(0x85), w(0x86), w(0x87),\ - w(0x88), w(0x89), w(0x8a), w(0x8b), w(0x8c), w(0x8d), w(0x8e), w(0x8f),\ - w(0x90), w(0x91), w(0x92), w(0x93), w(0x94), w(0x95), w(0x96), w(0x97),\ - w(0x98), w(0x99), w(0x9a), w(0x9b), w(0x9c), w(0x9d), w(0x9e), w(0x9f),\ - w(0xa0), w(0xa1), w(0xa2), w(0xa3), w(0xa4), w(0xa5), w(0xa6), w(0xa7),\ - w(0xa8), w(0xa9), w(0xaa), w(0xab), w(0xac), w(0xad), w(0xae), w(0xaf),\ - w(0xb0), w(0xb1), w(0xb2), w(0xb3), w(0xb4), w(0xb5), w(0xb6), w(0xb7),\ - w(0xb8), w(0xb9), w(0xba), w(0xbb), w(0xbc), w(0xbd), w(0xbe), w(0xbf),\ - w(0xc0), w(0xc1), w(0xc2), w(0xc3), w(0xc4), w(0xc5), w(0xc6), w(0xc7),\ - w(0xc8), w(0xc9), w(0xca), w(0xcb), w(0xcc), w(0xcd), w(0xce), w(0xcf),\ - w(0xd0), w(0xd1), w(0xd2), w(0xd3), w(0xd4), w(0xd5), w(0xd6), w(0xd7),\ - w(0xd8), w(0xd9), w(0xda), w(0xdb), w(0xdc), w(0xdd), w(0xde), w(0xdf),\ - w(0xe0), w(0xe1), w(0xe2), w(0xe3), w(0xe4), w(0xe5), w(0xe6), w(0xe7),\ - w(0xe8), w(0xe9), w(0xea), w(0xeb), w(0xec), w(0xed), w(0xee), w(0xef),\ - w(0xf0), w(0xf1), w(0xf2), w(0xf3), w(0xf4), w(0xf5), w(0xf6), w(0xf7),\ - w(0xf8), w(0xf9), w(0xfa), w(0xfb), w(0xfc), w(0xfd), w(0xfe), w(0xff) } - -#define rc_data(w) {\ - w(0x01), w(0x02), w(0x04), w(0x08), w(0x10),w(0x20), w(0x40), w(0x80),\ - w(0x1b), w(0x36) } - -#define h0(x) (x) - -#define w0(p) bytes2word(p, 0, 0, 0) -#define w1(p) bytes2word(0, p, 0, 0) -#define w2(p) bytes2word(0, 0, p, 0) -#define w3(p) bytes2word(0, 0, 0, p) - -#define u0(p) bytes2word(f2(p), p, p, f3(p)) -#define u1(p) bytes2word(f3(p), f2(p), p, p) -#define u2(p) bytes2word(p, f3(p), f2(p), p) -#define u3(p) bytes2word(p, p, f3(p), f2(p)) - -#define v0(p) bytes2word(fe(p), f9(p), fd(p), fb(p)) -#define v1(p) bytes2word(fb(p), fe(p), f9(p), fd(p)) -#define v2(p) bytes2word(fd(p), fb(p), fe(p), f9(p)) -#define v3(p) bytes2word(f9(p), fd(p), fb(p), fe(p)) - -#endif - -#if defined(FIXED_TABLES) || !defined(FF_TABLES) - -#define f2(x) ((x<<1) ^ (((x>>7) & 1) * WPOLY)) -#define f4(x) ((x<<2) ^ (((x>>6) & 1) * WPOLY) ^ (((x>>6) & 2) * WPOLY)) -#define f8(x) ((x<<3) ^ (((x>>5) & 1) * WPOLY) ^ (((x>>5) & 2) * WPOLY) \ - ^ (((x>>5) & 4) * WPOLY)) -#define f3(x) (f2(x) ^ x) -#define f9(x) (f8(x) ^ x) -#define fb(x) (f8(x) ^ f2(x) ^ x) -#define fd(x) (f8(x) ^ f4(x) ^ x) -#define fe(x) (f8(x) ^ f4(x) ^ f2(x)) - -#else - -#define f2(x) ((x) ? pow[log[x] + 0x19] : 0) -#define f3(x) ((x) ? pow[log[x] + 0x01] : 0) -#define f9(x) ((x) ? pow[log[x] + 0xc7] : 0) -#define fb(x) ((x) ? pow[log[x] + 0x68] : 0) -#define fd(x) ((x) ? pow[log[x] + 0xee] : 0) -#define fe(x) ((x) ? pow[log[x] + 0xdf] : 0) -#define fi(x) ((x) ? pow[ 255 - log[x]] : 0) - -#endif - -#include "aestab.h" - -#if defined(FIXED_TABLES) - -/* implemented in case of wrong call for fixed tables */ - -void gen_tabs(void) -{ -} - -#else /* dynamic table generation */ - -#if !defined(FF_TABLES) - -/* Generate the tables for the dynamic table option - - It will generally be sensible to use tables to compute finite - field multiplies and inverses but where memory is scarse this - code might sometimes be better. But it only has effect during - initialisation so its pretty unimportant in overall terms. -*/ - -/* return 2 ^ (n - 1) where n is the bit number of the highest bit - set in x with x in the range 1 < x < 0x00000200. This form is - used so that locals within fi can be bytes rather than words -*/ - -static aes_08t hibit(const aes_32t x) -{ aes_08t r = (aes_08t)((x >> 1) | (x >> 2)); - - r |= (r >> 2); - r |= (r >> 4); - return (r + 1) >> 1; -} - -/* return the inverse of the finite field element x */ - -static aes_08t fi(const aes_08t x) -{ aes_08t p1 = x, p2 = BPOLY, n1 = hibit(x), n2 = 0x80, v1 = 1, v2 = 0; - - if(x < 2) return x; - - for(;;) - { - if(!n1) return v1; - - while(n2 >= n1) - { - n2 /= n1; p2 ^= p1 * n2; v2 ^= v1 * n2; n2 = hibit(p2); - } - - if(!n2) return v2; - - while(n1 >= n2) - { - n1 /= n2; p1 ^= p2 * n1; v1 ^= v2 * n1; n1 = hibit(p1); - } - } -} - -#endif - -/* The forward and inverse affine transformations used in the S-box */ - -#define fwd_affine(x) \ - (w = (aes_32t)x, w ^= (w<<1)^(w<<2)^(w<<3)^(w<<4), 0x63^(aes_08t)(w^(w>>8))) - -#define inv_affine(x) \ - (w = (aes_32t)x, w = (w<<1)^(w<<3)^(w<<6), 0x05^(aes_08t)(w^(w>>8))) - -static int init = 0; - -void gen_tabs(void) -{ aes_32t i, w; - -#if defined(FF_TABLES) - - aes_08t pow[512], log[256]; - - if(init) return; - /* log and power tables for GF(2^8) finite field with - WPOLY as modular polynomial - the simplest primitive - root is 0x03, used here to generate the tables - */ - - i = 0; w = 1; - do - { - pow[i] = (aes_08t)w; - pow[i + 255] = (aes_08t)w; - log[w] = (aes_08t)i++; - w ^= (w << 1) ^ (w & 0x80 ? WPOLY : 0); - } - while (w != 1); - -#else - if(init) return; -#endif - - for(i = 0, w = 1; i < RC_LENGTH; ++i) - { - t_set(r,c)[i] = bytes2word(w, 0, 0, 0); - w = f2(w); - } - - for(i = 0; i < 256; ++i) - { aes_08t b; - - b = fwd_affine(fi((aes_08t)i)); - w = bytes2word(f2(b), b, b, f3(b)); - -#if defined( SBX_SET ) - t_set(s,box)[i] = b; -#endif - -#if defined( FT1_SET ) /* tables for a normal encryption round */ - t_set(f,n)[i] = w; -#endif -#if defined( FT4_SET ) - t_set(f,n)[0][i] = w; - t_set(f,n)[1][i] = upr(w,1); - t_set(f,n)[2][i] = upr(w,2); - t_set(f,n)[3][i] = upr(w,3); -#endif - w = bytes2word(b, 0, 0, 0); - -#if defined( FL1_SET ) /* tables for last encryption round (may also */ - t_set(f,l)[i] = w; /* be used in the key schedule) */ -#endif -#if defined( FL4_SET ) - t_set(f,l)[0][i] = w; - t_set(f,l)[1][i] = upr(w,1); - t_set(f,l)[2][i] = upr(w,2); - t_set(f,l)[3][i] = upr(w,3); -#endif - -#if defined( LS1_SET ) /* table for key schedule if t_set(f,l) above is */ - t_set(l,s)[i] = w; /* not of the required form */ -#endif -#if defined( LS4_SET ) - t_set(l,s)[0][i] = w; - t_set(l,s)[1][i] = upr(w,1); - t_set(l,s)[2][i] = upr(w,2); - t_set(l,s)[3][i] = upr(w,3); -#endif - - b = fi(inv_affine((aes_08t)i)); - w = bytes2word(fe(b), f9(b), fd(b), fb(b)); - -#if defined( IM1_SET ) /* tables for the inverse mix column operation */ - t_set(i,m)[b] = w; -#endif -#if defined( IM4_SET ) - t_set(i,m)[0][b] = w; - t_set(i,m)[1][b] = upr(w,1); - t_set(i,m)[2][b] = upr(w,2); - t_set(i,m)[3][b] = upr(w,3); -#endif - -#if defined( ISB_SET ) - t_set(i,box)[i] = b; -#endif -#if defined( IT1_SET ) /* tables for a normal decryption round */ - t_set(i,n)[i] = w; -#endif -#if defined( IT4_SET ) - t_set(i,n)[0][i] = w; - t_set(i,n)[1][i] = upr(w,1); - t_set(i,n)[2][i] = upr(w,2); - t_set(i,n)[3][i] = upr(w,3); -#endif - w = bytes2word(b, 0, 0, 0); -#if defined( IL1_SET ) /* tables for last decryption round */ - t_set(i,l)[i] = w; -#endif -#if defined( IL4_SET ) - t_set(i,l)[0][i] = w; - t_set(i,l)[1][i] = upr(w,1); - t_set(i,l)[2][i] = upr(w,2); - t_set(i,l)[3][i] = upr(w,3); -#endif - } - init = 1; -} - -#endif - -#if defined(__cplusplus) -} -#endif - +/* + --------------------------------------------------------------------------- + Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. + + LICENSE TERMS + + The free distribution and use of this software in both source and binary + form is allowed (with or without changes) provided that: + + 1. distributions of this source code include the above copyright + notice, this list of conditions and the following disclaimer; + + 2. distributions in binary form include the above copyright + notice, this list of conditions and the following disclaimer + in the documentation and/or other associated materials; + + 3. the copyright holder's name is not used to endorse products + built using this software without specific written permission. + + ALTERNATIVELY, provided that this notice is retained in full, this product + may be distributed under the terms of the GNU General Public License (GPL), + in which case the provisions of the GPL apply INSTEAD OF those given above. + + DISCLAIMER + + This software is provided 'as is' with no explicit or implied warranties + in respect of its properties, including, but not limited to, correctness + and/or fitness for purpose. + --------------------------------------------------------------------------- + Issue 28/01/2004 + +*/ + +#if defined(__cplusplus) +extern "C" +{ +#endif + +#define DO_TABLES + +#include "aesopt.h" + +#if defined(FIXED_TABLES) + +#define sb_data(w) {\ + w(0x63), w(0x7c), w(0x77), w(0x7b), w(0xf2), w(0x6b), w(0x6f), w(0xc5),\ + w(0x30), w(0x01), w(0x67), w(0x2b), w(0xfe), w(0xd7), w(0xab), w(0x76),\ + w(0xca), w(0x82), w(0xc9), w(0x7d), w(0xfa), w(0x59), w(0x47), w(0xf0),\ + w(0xad), w(0xd4), w(0xa2), w(0xaf), w(0x9c), w(0xa4), w(0x72), w(0xc0),\ + w(0xb7), w(0xfd), w(0x93), w(0x26), w(0x36), w(0x3f), w(0xf7), w(0xcc),\ + w(0x34), w(0xa5), w(0xe5), w(0xf1), w(0x71), w(0xd8), w(0x31), w(0x15),\ + w(0x04), w(0xc7), w(0x23), w(0xc3), w(0x18), w(0x96), w(0x05), w(0x9a),\ + w(0x07), w(0x12), w(0x80), w(0xe2), w(0xeb), w(0x27), w(0xb2), w(0x75),\ + w(0x09), w(0x83), w(0x2c), w(0x1a), w(0x1b), w(0x6e), w(0x5a), w(0xa0),\ + w(0x52), w(0x3b), w(0xd6), w(0xb3), w(0x29), w(0xe3), w(0x2f), w(0x84),\ + w(0x53), w(0xd1), w(0x00), w(0xed), w(0x20), w(0xfc), w(0xb1), w(0x5b),\ + w(0x6a), w(0xcb), w(0xbe), w(0x39), w(0x4a), w(0x4c), w(0x58), w(0xcf),\ + w(0xd0), w(0xef), w(0xaa), w(0xfb), w(0x43), w(0x4d), w(0x33), w(0x85),\ + w(0x45), w(0xf9), w(0x02), w(0x7f), w(0x50), w(0x3c), w(0x9f), w(0xa8),\ + w(0x51), w(0xa3), w(0x40), w(0x8f), w(0x92), w(0x9d), w(0x38), w(0xf5),\ + w(0xbc), w(0xb6), w(0xda), w(0x21), w(0x10), w(0xff), w(0xf3), w(0xd2),\ + w(0xcd), w(0x0c), w(0x13), w(0xec), w(0x5f), w(0x97), w(0x44), w(0x17),\ + w(0xc4), w(0xa7), w(0x7e), w(0x3d), w(0x64), w(0x5d), w(0x19), w(0x73),\ + w(0x60), w(0x81), w(0x4f), w(0xdc), w(0x22), w(0x2a), w(0x90), w(0x88),\ + w(0x46), w(0xee), w(0xb8), w(0x14), w(0xde), w(0x5e), w(0x0b), w(0xdb),\ + w(0xe0), w(0x32), w(0x3a), w(0x0a), w(0x49), w(0x06), w(0x24), w(0x5c),\ + w(0xc2), w(0xd3), w(0xac), w(0x62), w(0x91), w(0x95), w(0xe4), w(0x79),\ + w(0xe7), w(0xc8), w(0x37), w(0x6d), w(0x8d), w(0xd5), w(0x4e), w(0xa9),\ + w(0x6c), w(0x56), w(0xf4), w(0xea), w(0x65), w(0x7a), w(0xae), w(0x08),\ + w(0xba), w(0x78), w(0x25), w(0x2e), w(0x1c), w(0xa6), w(0xb4), w(0xc6),\ + w(0xe8), w(0xdd), w(0x74), w(0x1f), w(0x4b), w(0xbd), w(0x8b), w(0x8a),\ + w(0x70), w(0x3e), w(0xb5), w(0x66), w(0x48), w(0x03), w(0xf6), w(0x0e),\ + w(0x61), w(0x35), w(0x57), w(0xb9), w(0x86), w(0xc1), w(0x1d), w(0x9e),\ + w(0xe1), w(0xf8), w(0x98), w(0x11), w(0x69), w(0xd9), w(0x8e), w(0x94),\ + w(0x9b), w(0x1e), w(0x87), w(0xe9), w(0xce), w(0x55), w(0x28), w(0xdf),\ + w(0x8c), w(0xa1), w(0x89), w(0x0d), w(0xbf), w(0xe6), w(0x42), w(0x68),\ + w(0x41), w(0x99), w(0x2d), w(0x0f), w(0xb0), w(0x54), w(0xbb), w(0x16) } + +#define isb_data(w) {\ + w(0x52), w(0x09), w(0x6a), w(0xd5), w(0x30), w(0x36), w(0xa5), w(0x38),\ + w(0xbf), w(0x40), w(0xa3), w(0x9e), w(0x81), w(0xf3), w(0xd7), w(0xfb),\ + w(0x7c), w(0xe3), w(0x39), w(0x82), w(0x9b), w(0x2f), w(0xff), w(0x87),\ + w(0x34), w(0x8e), w(0x43), w(0x44), w(0xc4), w(0xde), w(0xe9), w(0xcb),\ + w(0x54), w(0x7b), w(0x94), w(0x32), w(0xa6), w(0xc2), w(0x23), w(0x3d),\ + w(0xee), w(0x4c), w(0x95), w(0x0b), w(0x42), w(0xfa), w(0xc3), w(0x4e),\ + w(0x08), w(0x2e), w(0xa1), w(0x66), w(0x28), w(0xd9), w(0x24), w(0xb2),\ + w(0x76), w(0x5b), w(0xa2), w(0x49), w(0x6d), w(0x8b), w(0xd1), w(0x25),\ + w(0x72), w(0xf8), w(0xf6), w(0x64), w(0x86), w(0x68), w(0x98), w(0x16),\ + w(0xd4), w(0xa4), w(0x5c), w(0xcc), w(0x5d), w(0x65), w(0xb6), w(0x92),\ + w(0x6c), w(0x70), w(0x48), w(0x50), w(0xfd), w(0xed), w(0xb9), w(0xda),\ + w(0x5e), w(0x15), w(0x46), w(0x57), w(0xa7), w(0x8d), w(0x9d), w(0x84),\ + w(0x90), w(0xd8), w(0xab), w(0x00), w(0x8c), w(0xbc), w(0xd3), w(0x0a),\ + w(0xf7), w(0xe4), w(0x58), w(0x05), w(0xb8), w(0xb3), w(0x45), w(0x06),\ + w(0xd0), w(0x2c), w(0x1e), w(0x8f), w(0xca), w(0x3f), w(0x0f), w(0x02),\ + w(0xc1), w(0xaf), w(0xbd), w(0x03), w(0x01), w(0x13), w(0x8a), w(0x6b),\ + w(0x3a), w(0x91), w(0x11), w(0x41), w(0x4f), w(0x67), w(0xdc), w(0xea),\ + w(0x97), w(0xf2), w(0xcf), w(0xce), w(0xf0), w(0xb4), w(0xe6), w(0x73),\ + w(0x96), w(0xac), w(0x74), w(0x22), w(0xe7), w(0xad), w(0x35), w(0x85),\ + w(0xe2), w(0xf9), w(0x37), w(0xe8), w(0x1c), w(0x75), w(0xdf), w(0x6e),\ + w(0x47), w(0xf1), w(0x1a), w(0x71), w(0x1d), w(0x29), w(0xc5), w(0x89),\ + w(0x6f), w(0xb7), w(0x62), w(0x0e), w(0xaa), w(0x18), w(0xbe), w(0x1b),\ + w(0xfc), w(0x56), w(0x3e), w(0x4b), w(0xc6), w(0xd2), w(0x79), w(0x20),\ + w(0x9a), w(0xdb), w(0xc0), w(0xfe), w(0x78), w(0xcd), w(0x5a), w(0xf4),\ + w(0x1f), w(0xdd), w(0xa8), w(0x33), w(0x88), w(0x07), w(0xc7), w(0x31),\ + w(0xb1), w(0x12), w(0x10), w(0x59), w(0x27), w(0x80), w(0xec), w(0x5f),\ + w(0x60), w(0x51), w(0x7f), w(0xa9), w(0x19), w(0xb5), w(0x4a), w(0x0d),\ + w(0x2d), w(0xe5), w(0x7a), w(0x9f), w(0x93), w(0xc9), w(0x9c), w(0xef),\ + w(0xa0), w(0xe0), w(0x3b), w(0x4d), w(0xae), w(0x2a), w(0xf5), w(0xb0),\ + w(0xc8), w(0xeb), w(0xbb), w(0x3c), w(0x83), w(0x53), w(0x99), w(0x61),\ + w(0x17), w(0x2b), w(0x04), w(0x7e), w(0xba), w(0x77), w(0xd6), w(0x26),\ + w(0xe1), w(0x69), w(0x14), w(0x63), w(0x55), w(0x21), w(0x0c), w(0x7d) } + +#define mm_data(w) {\ + w(0x00), w(0x01), w(0x02), w(0x03), w(0x04), w(0x05), w(0x06), w(0x07),\ + w(0x08), w(0x09), w(0x0a), w(0x0b), w(0x0c), w(0x0d), w(0x0e), w(0x0f),\ + w(0x10), w(0x11), w(0x12), w(0x13), w(0x14), w(0x15), w(0x16), w(0x17),\ + w(0x18), w(0x19), w(0x1a), w(0x1b), w(0x1c), w(0x1d), w(0x1e), w(0x1f),\ + w(0x20), w(0x21), w(0x22), w(0x23), w(0x24), w(0x25), w(0x26), w(0x27),\ + w(0x28), w(0x29), w(0x2a), w(0x2b), w(0x2c), w(0x2d), w(0x2e), w(0x2f),\ + w(0x30), w(0x31), w(0x32), w(0x33), w(0x34), w(0x35), w(0x36), w(0x37),\ + w(0x38), w(0x39), w(0x3a), w(0x3b), w(0x3c), w(0x3d), w(0x3e), w(0x3f),\ + w(0x40), w(0x41), w(0x42), w(0x43), w(0x44), w(0x45), w(0x46), w(0x47),\ + w(0x48), w(0x49), w(0x4a), w(0x4b), w(0x4c), w(0x4d), w(0x4e), w(0x4f),\ + w(0x50), w(0x51), w(0x52), w(0x53), w(0x54), w(0x55), w(0x56), w(0x57),\ + w(0x58), w(0x59), w(0x5a), w(0x5b), w(0x5c), w(0x5d), w(0x5e), w(0x5f),\ + w(0x60), w(0x61), w(0x62), w(0x63), w(0x64), w(0x65), w(0x66), w(0x67),\ + w(0x68), w(0x69), w(0x6a), w(0x6b), w(0x6c), w(0x6d), w(0x6e), w(0x6f),\ + w(0x70), w(0x71), w(0x72), w(0x73), w(0x74), w(0x75), w(0x76), w(0x77),\ + w(0x78), w(0x79), w(0x7a), w(0x7b), w(0x7c), w(0x7d), w(0x7e), w(0x7f),\ + w(0x80), w(0x81), w(0x82), w(0x83), w(0x84), w(0x85), w(0x86), w(0x87),\ + w(0x88), w(0x89), w(0x8a), w(0x8b), w(0x8c), w(0x8d), w(0x8e), w(0x8f),\ + w(0x90), w(0x91), w(0x92), w(0x93), w(0x94), w(0x95), w(0x96), w(0x97),\ + w(0x98), w(0x99), w(0x9a), w(0x9b), w(0x9c), w(0x9d), w(0x9e), w(0x9f),\ + w(0xa0), w(0xa1), w(0xa2), w(0xa3), w(0xa4), w(0xa5), w(0xa6), w(0xa7),\ + w(0xa8), w(0xa9), w(0xaa), w(0xab), w(0xac), w(0xad), w(0xae), w(0xaf),\ + w(0xb0), w(0xb1), w(0xb2), w(0xb3), w(0xb4), w(0xb5), w(0xb6), w(0xb7),\ + w(0xb8), w(0xb9), w(0xba), w(0xbb), w(0xbc), w(0xbd), w(0xbe), w(0xbf),\ + w(0xc0), w(0xc1), w(0xc2), w(0xc3), w(0xc4), w(0xc5), w(0xc6), w(0xc7),\ + w(0xc8), w(0xc9), w(0xca), w(0xcb), w(0xcc), w(0xcd), w(0xce), w(0xcf),\ + w(0xd0), w(0xd1), w(0xd2), w(0xd3), w(0xd4), w(0xd5), w(0xd6), w(0xd7),\ + w(0xd8), w(0xd9), w(0xda), w(0xdb), w(0xdc), w(0xdd), w(0xde), w(0xdf),\ + w(0xe0), w(0xe1), w(0xe2), w(0xe3), w(0xe4), w(0xe5), w(0xe6), w(0xe7),\ + w(0xe8), w(0xe9), w(0xea), w(0xeb), w(0xec), w(0xed), w(0xee), w(0xef),\ + w(0xf0), w(0xf1), w(0xf2), w(0xf3), w(0xf4), w(0xf5), w(0xf6), w(0xf7),\ + w(0xf8), w(0xf9), w(0xfa), w(0xfb), w(0xfc), w(0xfd), w(0xfe), w(0xff) } + +#define rc_data(w) {\ + w(0x01), w(0x02), w(0x04), w(0x08), w(0x10),w(0x20), w(0x40), w(0x80),\ + w(0x1b), w(0x36) } + +#define h0(x) (x) + +#define w0(p) bytes2word(p, 0, 0, 0) +#define w1(p) bytes2word(0, p, 0, 0) +#define w2(p) bytes2word(0, 0, p, 0) +#define w3(p) bytes2word(0, 0, 0, p) + +#define u0(p) bytes2word(f2(p), p, p, f3(p)) +#define u1(p) bytes2word(f3(p), f2(p), p, p) +#define u2(p) bytes2word(p, f3(p), f2(p), p) +#define u3(p) bytes2word(p, p, f3(p), f2(p)) + +#define v0(p) bytes2word(fe(p), f9(p), fd(p), fb(p)) +#define v1(p) bytes2word(fb(p), fe(p), f9(p), fd(p)) +#define v2(p) bytes2word(fd(p), fb(p), fe(p), f9(p)) +#define v3(p) bytes2word(f9(p), fd(p), fb(p), fe(p)) + +#endif + +#if defined(FIXED_TABLES) || !defined(FF_TABLES) + +#define f2(x) ((x<<1) ^ (((x>>7) & 1) * WPOLY)) +#define f4(x) ((x<<2) ^ (((x>>6) & 1) * WPOLY) ^ (((x>>6) & 2) * WPOLY)) +#define f8(x) ((x<<3) ^ (((x>>5) & 1) * WPOLY) ^ (((x>>5) & 2) * WPOLY) \ + ^ (((x>>5) & 4) * WPOLY)) +#define f3(x) (f2(x) ^ x) +#define f9(x) (f8(x) ^ x) +#define fb(x) (f8(x) ^ f2(x) ^ x) +#define fd(x) (f8(x) ^ f4(x) ^ x) +#define fe(x) (f8(x) ^ f4(x) ^ f2(x)) + +#else + +#define f2(x) ((x) ? pow[log[x] + 0x19] : 0) +#define f3(x) ((x) ? pow[log[x] + 0x01] : 0) +#define f9(x) ((x) ? pow[log[x] + 0xc7] : 0) +#define fb(x) ((x) ? pow[log[x] + 0x68] : 0) +#define fd(x) ((x) ? pow[log[x] + 0xee] : 0) +#define fe(x) ((x) ? pow[log[x] + 0xdf] : 0) +#define fi(x) ((x) ? pow[ 255 - log[x]] : 0) + +#endif + +#include "aestab.h" + +#if defined(FIXED_TABLES) + +/* implemented in case of wrong call for fixed tables */ + +void gen_tabs(void) +{ +} + +#else /* dynamic table generation */ + +#if !defined(FF_TABLES) + +/* Generate the tables for the dynamic table option + + It will generally be sensible to use tables to compute finite + field multiplies and inverses but where memory is scarse this + code might sometimes be better. But it only has effect during + initialisation so its pretty unimportant in overall terms. +*/ + +/* return 2 ^ (n - 1) where n is the bit number of the highest bit + set in x with x in the range 1 < x < 0x00000200. This form is + used so that locals within fi can be bytes rather than words +*/ + +static aes_08t hibit(const aes_32t x) +{ aes_08t r = (aes_08t)((x >> 1) | (x >> 2)); + + r |= (r >> 2); + r |= (r >> 4); + return (r + 1) >> 1; +} + +/* return the inverse of the finite field element x */ + +static aes_08t fi(const aes_08t x) +{ aes_08t p1 = x, p2 = BPOLY, n1 = hibit(x), n2 = 0x80, v1 = 1, v2 = 0; + + if(x < 2) return x; + + for(;;) + { + if(!n1) return v1; + + while(n2 >= n1) + { + n2 /= n1; p2 ^= p1 * n2; v2 ^= v1 * n2; n2 = hibit(p2); + } + + if(!n2) return v2; + + while(n1 >= n2) + { + n1 /= n2; p1 ^= p2 * n1; v1 ^= v2 * n1; n1 = hibit(p1); + } + } +} + +#endif + +/* The forward and inverse affine transformations used in the S-box */ + +#define fwd_affine(x) \ + (w = (aes_32t)x, w ^= (w<<1)^(w<<2)^(w<<3)^(w<<4), 0x63^(aes_08t)(w^(w>>8))) + +#define inv_affine(x) \ + (w = (aes_32t)x, w = (w<<1)^(w<<3)^(w<<6), 0x05^(aes_08t)(w^(w>>8))) + +static int init = 0; + +void gen_tabs(void) +{ aes_32t i, w; + +#if defined(FF_TABLES) + + aes_08t pow[512], log[256]; + + if(init) return; + /* log and power tables for GF(2^8) finite field with + WPOLY as modular polynomial - the simplest primitive + root is 0x03, used here to generate the tables + */ + + i = 0; w = 1; + do + { + pow[i] = (aes_08t)w; + pow[i + 255] = (aes_08t)w; + log[w] = (aes_08t)i++; + w ^= (w << 1) ^ (w & 0x80 ? WPOLY : 0); + } + while (w != 1); + +#else + if(init) return; +#endif + + for(i = 0, w = 1; i < RC_LENGTH; ++i) + { + t_set(r,c)[i] = bytes2word(w, 0, 0, 0); + w = f2(w); + } + + for(i = 0; i < 256; ++i) + { aes_08t b; + + b = fwd_affine(fi((aes_08t)i)); + w = bytes2word(f2(b), b, b, f3(b)); + +#if defined( SBX_SET ) + t_set(s,box)[i] = b; +#endif + +#if defined( FT1_SET ) /* tables for a normal encryption round */ + t_set(f,n)[i] = w; +#endif +#if defined( FT4_SET ) + t_set(f,n)[0][i] = w; + t_set(f,n)[1][i] = upr(w,1); + t_set(f,n)[2][i] = upr(w,2); + t_set(f,n)[3][i] = upr(w,3); +#endif + w = bytes2word(b, 0, 0, 0); + +#if defined( FL1_SET ) /* tables for last encryption round (may also */ + t_set(f,l)[i] = w; /* be used in the key schedule) */ +#endif +#if defined( FL4_SET ) + t_set(f,l)[0][i] = w; + t_set(f,l)[1][i] = upr(w,1); + t_set(f,l)[2][i] = upr(w,2); + t_set(f,l)[3][i] = upr(w,3); +#endif + +#if defined( LS1_SET ) /* table for key schedule if t_set(f,l) above is */ + t_set(l,s)[i] = w; /* not of the required form */ +#endif +#if defined( LS4_SET ) + t_set(l,s)[0][i] = w; + t_set(l,s)[1][i] = upr(w,1); + t_set(l,s)[2][i] = upr(w,2); + t_set(l,s)[3][i] = upr(w,3); +#endif + + b = fi(inv_affine((aes_08t)i)); + w = bytes2word(fe(b), f9(b), fd(b), fb(b)); + +#if defined( IM1_SET ) /* tables for the inverse mix column operation */ + t_set(i,m)[b] = w; +#endif +#if defined( IM4_SET ) + t_set(i,m)[0][b] = w; + t_set(i,m)[1][b] = upr(w,1); + t_set(i,m)[2][b] = upr(w,2); + t_set(i,m)[3][b] = upr(w,3); +#endif + +#if defined( ISB_SET ) + t_set(i,box)[i] = b; +#endif +#if defined( IT1_SET ) /* tables for a normal decryption round */ + t_set(i,n)[i] = w; +#endif +#if defined( IT4_SET ) + t_set(i,n)[0][i] = w; + t_set(i,n)[1][i] = upr(w,1); + t_set(i,n)[2][i] = upr(w,2); + t_set(i,n)[3][i] = upr(w,3); +#endif + w = bytes2word(b, 0, 0, 0); +#if defined( IL1_SET ) /* tables for last decryption round */ + t_set(i,l)[i] = w; +#endif +#if defined( IL4_SET ) + t_set(i,l)[0][i] = w; + t_set(i,l)[1][i] = upr(w,1); + t_set(i,l)[2][i] = upr(w,2); + t_set(i,l)[3][i] = upr(w,3); +#endif + } + init = 1; +} + +#endif + +#if defined(__cplusplus) +} +#endif + diff --git a/bsd/crypto/aes/aestab.h b/bsd/crypto/aes/aestab.h index c610f9d43..004ef9e74 100644 --- a/bsd/crypto/aes/aestab.h +++ b/bsd/crypto/aes/aestab.h @@ -1,175 +1,175 @@ -/* - --------------------------------------------------------------------------- - Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. - - LICENSE TERMS - - The free distribution and use of this software in both source and binary - form is allowed (with or without changes) provided that: - - 1. distributions of this source code include the above copyright - notice, this list of conditions and the following disclaimer; - - 2. distributions in binary form include the above copyright - notice, this list of conditions and the following disclaimer - in the documentation and/or other associated materials; - - 3. the copyright holder's name is not used to endorse products - built using this software without specific written permission. - - ALTERNATIVELY, provided that this notice is retained in full, this product - may be distributed under the terms of the GNU General Public License (GPL), - in which case the provisions of the GPL apply INSTEAD OF those given above. - - DISCLAIMER - - This software is provided 'as is' with no explicit or implied warranties - in respect of its properties, including, but not limited to, correctness - and/or fitness for purpose. - --------------------------------------------------------------------------- - Issue 28/01/2004 - - This file contains the code for declaring the tables needed to implement - AES. The file aesopt.h is assumed to be included before this header file. - If there are no global variables, the definitions here can be used to put - the AES tables in a structure so that a pointer can then be added to the - AES context to pass them to the AES routines that need them. If this - facility is used, the calling program has to ensure that this pointer is - managed appropriately. In particular, the value of the t_dec(in,it) item - in the table structure must be set to zero in order to ensure that the - tables are initialised. In practice the three code sequences in aeskey.c - that control the calls to gen_tabs() and the gen_tabs() routine itself will - have to be changed for a specific implementation. If global variables are - available it will generally be preferable to use them with the precomputed - FIXED_TABLES option that uses static global tables. - - The following defines can be used to control the way the tables - are defined, initialised and used in embedded environments that - require special features for these purposes - - the 't_dec' construction is used to declare fixed table arrays - the 't_set' construction is used to set fixed table values - the 't_use' construction is used to access fixed table values - - 256 byte tables: - - t_xxx(s,box) => forward S box - t_xxx(i,box) => inverse S box - - 256 32-bit word OR 4 x 256 32-bit word tables: - - t_xxx(f,n) => forward normal round - t_xxx(f,l) => forward last round - t_xxx(i,n) => inverse normal round - t_xxx(i,l) => inverse last round - t_xxx(l,s) => key schedule table - t_xxx(i,m) => key schedule table - - Other variables and tables: - - t_xxx(r,c) => the rcon table -*/ - -#if !defined( _AESTAB_H ) -#define _AESTAB_H - -#define t_dec(m,n) t_##m##n -#define t_set(m,n) t_##m##n -#define t_use(m,n) t_##m##n - -#if defined(FIXED_TABLES) -#define Const const -#else -#define Const -#endif - -#if defined(DO_TABLES) -#define Extern -#else -#define Extern extern -#endif - -#if defined(_MSC_VER) && defined(TABLE_ALIGN) -#define Align __declspec(align(TABLE_ALIGN)) -#else -#define Align -#endif - -#if defined(__cplusplus) -extern "C" -{ -#endif - -#if defined(DO_TABLES) && defined(FIXED_TABLES) -#define d_1(t,n,b,e) Align Const t n[256] = b(e) -#define d_4(t,n,b,e,f,g,h) Align Const t n[4][256] = { b(e), b(f), b(g), b(h) } -Extern Align Const aes_32t t_dec(r,c)[RC_LENGTH] = rc_data(w0); -#else -#define d_1(t,n,b,e) Extern Align Const t n[256] -#define d_4(t,n,b,e,f,g,h) Extern Align Const t n[4][256] -Extern Align Const aes_32t t_dec(r,c)[RC_LENGTH]; -#endif - -#if defined( SBX_SET ) - d_1(aes_08t, t_dec(s,box), sb_data, h0); -#endif -#if defined( ISB_SET ) - d_1(aes_08t, t_dec(i,box), isb_data, h0); -#endif - -#if defined( FT1_SET ) - d_1(aes_32t, t_dec(f,n), sb_data, u0); -#endif -#if defined( FT4_SET ) - d_4(aes_32t, t_dec(f,n), sb_data, u0, u1, u2, u3); -#endif - -#if defined( FL1_SET ) - d_1(aes_32t, t_dec(f,l), sb_data, w0); -#endif -#if defined( FL4_SET ) - d_4(aes_32t, t_dec(f,l), sb_data, w0, w1, w2, w3); -#endif - -#if defined( IT1_SET ) - d_1(aes_32t, t_dec(i,n), isb_data, v0); -#endif -#if defined( IT4_SET ) - d_4(aes_32t, t_dec(i,n), isb_data, v0, v1, v2, v3); -#endif - -#if defined( IL1_SET ) - d_1(aes_32t, t_dec(i,l), isb_data, w0); -#endif -#if defined( IL4_SET ) - d_4(aes_32t, t_dec(i,l), isb_data, w0, w1, w2, w3); -#endif - -#if defined( LS1_SET ) -#if defined( FL1_SET ) -#undef LS1_SET -#else - d_1(aes_32t, t_dec(l,s), sb_data, w0); -#endif -#endif - -#if defined( LS4_SET ) -#if defined( FL4_SET ) -#undef LS4_SET -#else - d_4(aes_32t, t_dec(l,s), sb_data, w0, w1, w2, w3); -#endif -#endif - -#if defined( IM1_SET ) - d_1(aes_32t, t_dec(i,m), mm_data, v0); -#endif -#if defined( IM4_SET ) - d_4(aes_32t, t_dec(i,m), mm_data, v0, v1, v2, v3); -#endif - -#if defined(__cplusplus) -} -#endif - -#endif +/* + --------------------------------------------------------------------------- + Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved. + + LICENSE TERMS + + The free distribution and use of this software in both source and binary + form is allowed (with or without changes) provided that: + + 1. distributions of this source code include the above copyright + notice, this list of conditions and the following disclaimer; + + 2. distributions in binary form include the above copyright + notice, this list of conditions and the following disclaimer + in the documentation and/or other associated materials; + + 3. the copyright holder's name is not used to endorse products + built using this software without specific written permission. + + ALTERNATIVELY, provided that this notice is retained in full, this product + may be distributed under the terms of the GNU General Public License (GPL), + in which case the provisions of the GPL apply INSTEAD OF those given above. + + DISCLAIMER + + This software is provided 'as is' with no explicit or implied warranties + in respect of its properties, including, but not limited to, correctness + and/or fitness for purpose. + --------------------------------------------------------------------------- + Issue 28/01/2004 + + This file contains the code for declaring the tables needed to implement + AES. The file aesopt.h is assumed to be included before this header file. + If there are no global variables, the definitions here can be used to put + the AES tables in a structure so that a pointer can then be added to the + AES context to pass them to the AES routines that need them. If this + facility is used, the calling program has to ensure that this pointer is + managed appropriately. In particular, the value of the t_dec(in,it) item + in the table structure must be set to zero in order to ensure that the + tables are initialised. In practice the three code sequences in aeskey.c + that control the calls to gen_tabs() and the gen_tabs() routine itself will + have to be changed for a specific implementation. If global variables are + available it will generally be preferable to use them with the precomputed + FIXED_TABLES option that uses static global tables. + + The following defines can be used to control the way the tables + are defined, initialised and used in embedded environments that + require special features for these purposes + + the 't_dec' construction is used to declare fixed table arrays + the 't_set' construction is used to set fixed table values + the 't_use' construction is used to access fixed table values + + 256 byte tables: + + t_xxx(s,box) => forward S box + t_xxx(i,box) => inverse S box + + 256 32-bit word OR 4 x 256 32-bit word tables: + + t_xxx(f,n) => forward normal round + t_xxx(f,l) => forward last round + t_xxx(i,n) => inverse normal round + t_xxx(i,l) => inverse last round + t_xxx(l,s) => key schedule table + t_xxx(i,m) => key schedule table + + Other variables and tables: + + t_xxx(r,c) => the rcon table +*/ + +#if !defined( _AESTAB_H ) +#define _AESTAB_H + +#define t_dec(m,n) t_##m##n +#define t_set(m,n) t_##m##n +#define t_use(m,n) t_##m##n + +#if defined(FIXED_TABLES) +#define Const const +#else +#define Const +#endif + +#if defined(DO_TABLES) +#define Extern +#else +#define Extern extern +#endif + +#if defined(_MSC_VER) && defined(TABLE_ALIGN) +#define Align __declspec(align(TABLE_ALIGN)) +#else +#define Align +#endif + +#if defined(__cplusplus) +extern "C" +{ +#endif + +#if defined(DO_TABLES) && defined(FIXED_TABLES) +#define d_1(t,n,b,e) Align Const t n[256] = b(e) +#define d_4(t,n,b,e,f,g,h) Align Const t n[4][256] = { b(e), b(f), b(g), b(h) } +Extern Align Const aes_32t t_dec(r,c)[RC_LENGTH] = rc_data(w0); +#else +#define d_1(t,n,b,e) Extern Align Const t n[256] +#define d_4(t,n,b,e,f,g,h) Extern Align Const t n[4][256] +Extern Align Const aes_32t t_dec(r,c)[RC_LENGTH]; +#endif + +#if defined( SBX_SET ) + d_1(aes_08t, t_dec(s,box), sb_data, h0); +#endif +#if defined( ISB_SET ) + d_1(aes_08t, t_dec(i,box), isb_data, h0); +#endif + +#if defined( FT1_SET ) + d_1(aes_32t, t_dec(f,n), sb_data, u0); +#endif +#if defined( FT4_SET ) + d_4(aes_32t, t_dec(f,n), sb_data, u0, u1, u2, u3); +#endif + +#if defined( FL1_SET ) + d_1(aes_32t, t_dec(f,l), sb_data, w0); +#endif +#if defined( FL4_SET ) + d_4(aes_32t, t_dec(f,l), sb_data, w0, w1, w2, w3); +#endif + +#if defined( IT1_SET ) + d_1(aes_32t, t_dec(i,n), isb_data, v0); +#endif +#if defined( IT4_SET ) + d_4(aes_32t, t_dec(i,n), isb_data, v0, v1, v2, v3); +#endif + +#if defined( IL1_SET ) + d_1(aes_32t, t_dec(i,l), isb_data, w0); +#endif +#if defined( IL4_SET ) + d_4(aes_32t, t_dec(i,l), isb_data, w0, w1, w2, w3); +#endif + +#if defined( LS1_SET ) +#if defined( FL1_SET ) +#undef LS1_SET +#else + d_1(aes_32t, t_dec(l,s), sb_data, w0); +#endif +#endif + +#if defined( LS4_SET ) +#if defined( FL4_SET ) +#undef LS4_SET +#else + d_4(aes_32t, t_dec(l,s), sb_data, w0, w1, w2, w3); +#endif +#endif + +#if defined( IM1_SET ) + d_1(aes_32t, t_dec(i,m), mm_data, v0); +#endif +#if defined( IM4_SET ) + d_4(aes_32t, t_dec(i,m), mm_data, v0, v1, v2, v3); +#endif + +#if defined(__cplusplus) +} +#endif + +#endif diff --git a/bsd/dev/ppc/kern_machdep.c b/bsd/dev/ppc/kern_machdep.c index 9aefbe8ba..622e80e7b 100644 --- a/bsd/dev/ppc/kern_machdep.c +++ b/bsd/dev/ppc/kern_machdep.c @@ -221,6 +221,8 @@ grade_binary(cpu_type_t exectype, cpu_subtype_t execsubtype) /* NOTREACHED */ } +extern vm_map_offset_t kvtophys64(vm_map_offset_t); + boolean_t kernacc( off_t start, @@ -234,7 +236,7 @@ kernacc( end = start + len; while (base < end) { - if(kvtophys((vm_offset_t)base) == NULL) + if(kvtophys64((vm_map_offset_t)base) == (vm_map_offset_t)0) return(FALSE); base += page_size; } diff --git a/bsd/hfs/hfs_search.c b/bsd/hfs/hfs_search.c index 0d013ced4..1432a7c69 100644 --- a/bsd/hfs/hfs_search.c +++ b/bsd/hfs/hfs_search.c @@ -99,7 +99,7 @@ static int CheckCriteria( ExtendedVCB *vcb, searchinfospec_t *searchInfo2, Boolean lookForDup ); -static int CheckAccess(ExtendedVCB *vcb, u_long searchBits, CatalogKey *key, struct proc *p); +static int CheckAccess(ExtendedVCB *vcb, u_long searchBits, CatalogKey *key, struct vfs_context *ctx); static int InsertMatch(struct hfsmount *hfsmp, uio_t a_uio, CatalogRecord *rec, CatalogKey *key, struct attrlist *returnAttrList, @@ -206,7 +206,7 @@ hfs_vnop_search(ap) attrs = ap->a_searchattrs->commonattr | ap->a_returnattrs->commonattr; if (attrs & (ATTR_CMN_NAME | ATTR_CMN_PAROBJID)) return (EINVAL); - if ((err = suser(kauth_cred_get(), 0))) + if ((err = vfs_context_suser(ap->a_context))) return (err); } @@ -307,7 +307,7 @@ hfs_vnop_search(ap) hfs_systemfile_unlock(hfsmp, lockflags); if (CheckCriteria(vcb, ap->a_options, ap->a_searchattrs, &rec, keyp, &searchInfo1, &searchInfo2, false) && - CheckAccess(vcb, ap->a_options, keyp, p)) { + CheckAccess(vcb, ap->a_options, keyp, ap->a_context)) { result = InsertMatch(hfsmp, ap->a_uio, &rec, keyp, ap->a_returnattrs, @@ -365,7 +365,7 @@ hfs_vnop_search(ap) } if (CheckCriteria( vcb, ap->a_options, ap->a_searchattrs, myCurrentDataPtr, myCurrentKeyPtr, &searchInfo1, &searchInfo2, true ) - && CheckAccess(vcb, ap->a_options, myCurrentKeyPtr, p)) { + && CheckAccess(vcb, ap->a_options, myCurrentKeyPtr, ap->a_context)) { err = InsertMatch(hfsmp, ap->a_uio, myCurrentDataPtr, myCurrentKeyPtr, ap->a_returnattrs, attributesBuffer, variableBuffer, ap->a_nummatches); @@ -537,7 +537,7 @@ is_inappropriate_name(char *name, int len) */ static int -CheckAccess(ExtendedVCB *theVCBPtr, u_long searchBits, CatalogKey *theKeyPtr, struct proc *theProcPtr) +CheckAccess(ExtendedVCB *theVCBPtr, u_long searchBits, CatalogKey *theKeyPtr, struct vfs_context *ctx) { Boolean isHFSPlus; int myErr; @@ -546,13 +546,10 @@ CheckAccess(ExtendedVCB *theVCBPtr, u_long searchBits, CatalogKey *theKeyPtr, st hfsmount_t * hfsmp; struct FndrDirInfo *finfop; struct vnode * vp = NULL; - struct vfs_context my_context; myResult = 0; /* default to "no access" */ - my_context.vc_proc = theProcPtr; - my_context.vc_ucred = kauth_cred_get(); - if (!proc_suser(theProcPtr)) { + if (!vfs_context_suser(ctx)) { myResult = 1; /* allow access */ goto ExitThisRoutine; /* root always has access */ } @@ -602,9 +599,9 @@ CheckAccess(ExtendedVCB *theVCBPtr, u_long searchBits, CatalogKey *theKeyPtr, st myNodeID = cp->c_parentcnid; /* move up the hierarchy */ hfs_unlock(VTOC(vp)); if (vp->v_type == VDIR) { - myErr = vnode_authorize(vp, NULL, (KAUTH_VNODE_SEARCH | KAUTH_VNODE_LIST_DIRECTORY), &my_context); + myErr = vnode_authorize(vp, NULL, (KAUTH_VNODE_SEARCH | KAUTH_VNODE_LIST_DIRECTORY), ctx); } else { - myErr = vnode_authorize(vp, NULL, (KAUTH_VNODE_SEARCH), &my_context); + myErr = vnode_authorize(vp, NULL, (KAUTH_VNODE_SEARCH), ctx); } vnode_put(vp); vp = NULL; diff --git a/bsd/hfs/hfs_vfsutils.c b/bsd/hfs/hfs_vfsutils.c index 4336e8732..7e55787f8 100644 --- a/bsd/hfs/hfs_vfsutils.c +++ b/bsd/hfs/hfs_vfsutils.c @@ -529,6 +529,8 @@ OSErr hfs_MountHFSPlusVolume(struct hfsmount *hfsmp, HFSPlusVolumeHeader *vhp, /* Pick up volume name and create date */ retval = cat_idlookup(hfsmp, kHFSRootFolderID, &cndesc, &cnattr, NULL); if (retval) { + if (hfsmp->hfs_attribute_vp) + hfs_unlock(VTOC(hfsmp->hfs_attribute_vp)); hfs_unlock(VTOC(hfsmp->hfs_allocation_vp)); hfs_unlock(VTOC(hfsmp->hfs_catalog_vp)); hfs_unlock(VTOC(hfsmp->hfs_extents_vp)); diff --git a/bsd/kern/kern_aio.c b/bsd/kern/kern_aio.c index 386774f05..e913df014 100644 --- a/bsd/kern/kern_aio.c +++ b/bsd/kern/kern_aio.c @@ -2061,11 +2061,15 @@ do_aio_write( aio_workq_entry *entryp ) return(EBADF); } if ( fp != NULL ) { - error = dofilewrite( entryp->procp, fp, entryp->aiocb.aio_fildes, - entryp->aiocb.aio_buf, - entryp->aiocb.aio_nbytes, - entryp->aiocb.aio_offset, FOF_OFFSET, - &entryp->returnval ); + /* NB: tell dofilewrite the offset, and to use the proc cred */ + error = dofilewrite( entryp->procp, + fp, + entryp->aiocb.aio_fildes, + entryp->aiocb.aio_buf, + entryp->aiocb.aio_nbytes, + entryp->aiocb.aio_offset, + FOF_OFFSET | FOF_PCRED, + &entryp->returnval); fp_drop(entryp->procp, entryp->aiocb.aio_fildes, fp, 0); } diff --git a/bsd/kern/kern_mman.c b/bsd/kern/kern_mman.c index f91cbf079..27d9cc1f1 100644 --- a/bsd/kern/kern_mman.c +++ b/bsd/kern/kern_mman.c @@ -455,7 +455,7 @@ mmap(struct proc *p, struct mmap_args *uap, user_addr_t *retval) * with ones that only work for read. */ - ubc_setcred(vp, p); + ubc_setthreadcred(vp, p, current_thread()); docow = FALSE; if ((flags & (MAP_ANON|MAP_SHARED)) == 0) { docow = TRUE; @@ -1128,7 +1128,7 @@ map_fd_funneled( } } - ubc_setcred(vp, current_proc()); + ubc_setthreadcred(vp, current_proc(), current_thread()); (void)ubc_map(vp, (PROT_READ | PROT_WRITE | PROT_EXEC)); (void)vnode_put(vp); err = 0; diff --git a/bsd/kern/kern_prot.c b/bsd/kern/kern_prot.c index 1a963663b..c7721f14d 100644 --- a/bsd/kern/kern_prot.c +++ b/bsd/kern/kern_prot.c @@ -722,6 +722,7 @@ setgroups1(struct proc *p, u_int gidsetsize, user_addr_t gidset, uid_t gmuid, __ gid_t newgroups[NGROUPS] = { 0 }; int error; kauth_cred_t my_cred, my_new_cred; + struct uthread *uthread = get_bsdthread_info(current_thread()); if ((error = suser(p->p_ucred, &p->p_acflag))) return (error); @@ -740,39 +741,64 @@ setgroups1(struct proc *p, u_int gidsetsize, user_addr_t gidset, uid_t gmuid, __ } } - /* get current credential and take a reference while we muck with it */ - for (;;) { - my_cred = kauth_cred_proc_ref(p); + if ((uthread->uu_flag & UT_SETUID) != 0) { + /* + * If this thread is under an assumed identity, set the + * supplementary grouplist on the thread credential instead + * of the process one. If we were the only reference holder, + * the credential is updated in place, otherwise, our reference + * is dropped and we get back a different cred with a reference + * already held on it. Because this is per-thread, we don't + * need the referencing/locking/retry required for per-process. + * + * Hack: this opts into memberd to avoid needing to use a per + * thread credential initgroups() instead of setgroups() in + * AFP server to address <rdar://4561060> + */ + my_cred = uthread->uu_ucred; + uthread->uu_ucred = kauth_cred_setgroups(my_cred, &newgroups[0], ngrp, my_cred->cr_gmuid); + } else { - /* - * set the credential with new info. If there is no change we get back - * the same credential we passed in. + /* + * get current credential and take a reference while we muck + * with it */ - my_new_cred = kauth_cred_setgroups(p->p_ucred, &newgroups[0], ngrp, gmuid); - if (my_cred != my_new_cred) { - proc_lock(p); - /* need to protect for a race where another thread also changed - * the credential after we took our reference. If p_ucred has - * changed then we should restart this again with the new cred. + for (;;) { + my_cred = kauth_cred_proc_ref(p); + + /* + * set the credential with new info. If there is no + * change we get back the same credential we passed in. */ - if (p->p_ucred != my_cred) { + my_new_cred = kauth_cred_setgroups(my_cred, &newgroups[0], ngrp, gmuid); + if (my_cred != my_new_cred) { + proc_lock(p); + /* + * need to protect for a race where another + * thread also changed the credential after we + * took our reference. If p_ucred has + * changed then we should restart this again + * with the new cred. + */ + if (p->p_ucred != my_cred) { + proc_unlock(p); + kauth_cred_rele(my_cred); + kauth_cred_rele(my_new_cred); + /* try again */ + continue; + } + p->p_ucred = my_new_cred; + p->p_flag |= P_SUGID; proc_unlock(p); - kauth_cred_rele(my_cred); - kauth_cred_rele(my_new_cred); - /* try again */ - continue; } - p->p_ucred = my_new_cred; - p->p_flag |= P_SUGID; - proc_unlock(p); + /* drop our extra reference */ + kauth_cred_rele(my_cred); + break; } - /* drop our extra reference */ - kauth_cred_rele(my_cred); - break; - } - AUDIT_ARG(groupset, p->p_ucred->cr_groups, ngrp); - set_security_token(p); + AUDIT_ARG(groupset, p->p_ucred->cr_groups, ngrp); + set_security_token(p); + } return (0); } diff --git a/bsd/kern/ubc_subr.c b/bsd/kern/ubc_subr.c index 1660c5b7a..2cbd62364 100644 --- a/bsd/kern/ubc_subr.c +++ b/bsd/kern/ubc_subr.c @@ -45,6 +45,7 @@ #include <sys/proc_internal.h> #include <sys/kauth.h> #include <sys/buf.h> +#include <sys/user.h> #include <mach/mach_types.h> #include <mach/memory_object_types.h> @@ -54,6 +55,7 @@ #include <kern/kern_types.h> #include <kern/zalloc.h> +#include <kern/thread.h> #include <vm/vm_kern.h> #include <vm/vm_protos.h> /* last */ @@ -346,6 +348,35 @@ ubc_getcred(struct vnode *vp) return (NOCRED); } +int +ubc_setthreadcred(struct vnode *vp, struct proc *p, thread_t thread) +{ + struct ubc_info *uip; + kauth_cred_t credp; + struct uthread *uthread = get_bsdthread_info(thread); + + if (!UBCINFOEXISTS(vp)) + return (1); + + vnode_lock(vp); + + uip = vp->v_ubcinfo; + credp = uip->ui_ucred; + + if (credp == NOCRED) { + /* use per-thread cred, if assumed identity, else proc cred */ + if (uthread == NULL || (uthread->uu_flag & UT_SETUID) == 0) { + uip->ui_ucred = kauth_cred_proc_ref(p); + } else { + uip->ui_ucred = uthread->uu_ucred; + kauth_cred_ref(uip->ui_ucred); + } + } + vnode_unlock(vp); + + return (0); +} + /* * Set the credentials * existing credentials are not changed diff --git a/bsd/kern/uipc_socket2.c b/bsd/kern/uipc_socket2.c index a9287124f..ff81b933e 100644 --- a/bsd/kern/uipc_socket2.c +++ b/bsd/kern/uipc_socket2.c @@ -288,6 +288,12 @@ sonewconn_internal(head, connstatus) so->so_uid = head->so_uid; so->so_usecount = 1; +#ifdef __APPLE__ + so->so_rcv.sb_flags |= SB_RECV; /* XXX */ + so->so_rcv.sb_so = so->so_snd.sb_so = so; + TAILQ_INIT(&so->so_evlist); +#endif + if (soreserve(so, head->so_snd.sb_hiwat, head->so_rcv.sb_hiwat)) { sflt_termsock(so); sodealloc(so); @@ -321,11 +327,8 @@ sonewconn_internal(head, connstatus) head->so_incqlen++; } head->so_qlen++; -#ifdef __APPLE__ - so->so_rcv.sb_flags |= SB_RECV; /* XXX */ - so->so_rcv.sb_so = so->so_snd.sb_so = so; - TAILQ_INIT(&so->so_evlist); +#ifdef __APPLE__ /* Attach socket filters for this protocol */ sflt_initsock(so); #endif diff --git a/bsd/kern/uipc_usrreq.c b/bsd/kern/uipc_usrreq.c index a9a2de3c0..5ae9a884a 100644 --- a/bsd/kern/uipc_usrreq.c +++ b/bsd/kern/uipc_usrreq.c @@ -307,8 +307,13 @@ uipc_send(struct socket *so, int flags, struct mbuf *m, struct sockaddr *nam, goto release; } - if (control && (error = unp_internalize(control, p))) - goto release; + if (control) { + socket_unlock(so, 0); /* release global lock to avoid deadlock (4436174) */ + error = unp_internalize(control, p); + socket_lock(so, 0); + if (error) + goto release; + } switch (so->so_type) { case SOCK_DGRAM: diff --git a/bsd/miscfs/devfs/index.html b/bsd/miscfs/devfs/index.html index 2c1626603..a201382c6 100644 --- a/bsd/miscfs/devfs/index.html +++ b/bsd/miscfs/devfs/index.html @@ -1,22 +1,22 @@ -<HEAD> -<title>FTP Menu at ftp2.FreeBSD.ORG</title> -</HEAD> -<h1>FTP Menu</h1> -<HR> -<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/README"> -<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> README <br> -<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_proto.h"> -<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_proto.h <br> -<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_tree.c"> -<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_tree.c <br> -<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_vfsops.c"> -<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_vfsops.c <br> -<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_vnops.c"> -<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_vnops.c <br> -<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfsdefs.h"> -<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfsdefs.h <br> -<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/reproto.sh"> -<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> reproto.sh <br> -<br><hr> -<A HREF="http://-internal-/-http-gw-internal-/version.html">http-gw version 3.2 / 0</A> - (17.254.0.77) +<HEAD> +<title>FTP Menu at ftp2.FreeBSD.ORG</title> +</HEAD> +<h1>FTP Menu</h1> +<HR> +<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/README"> +<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> README <br> +<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_proto.h"> +<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_proto.h <br> +<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_tree.c"> +<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_tree.c <br> +<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_vfsops.c"> +<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_vfsops.c <br> +<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_vnops.c"> +<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_vnops.c <br> +<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfsdefs.h"> +<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfsdefs.h <br> +<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/reproto.sh"> +<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> reproto.sh <br> +<br><hr> +<A HREF="http://-internal-/-http-gw-internal-/version.html">http-gw version 3.2 / 0</A> + (17.254.0.77) diff --git a/bsd/net/ether_inet_pr_module.c b/bsd/net/ether_inet_pr_module.c index 43d413070..c3a518e28 100644 --- a/bsd/net/ether_inet_pr_module.c +++ b/bsd/net/ether_inet_pr_module.c @@ -128,8 +128,8 @@ inet_ether_arp_input( return; } - /* Verify the sender is not broadcast or multicast */ - if ((ea->arp_sha[0] & 0x01) != 0) { + /* Verify the sender is not broadcast */ + if (bcmp(ea->arp_sha, etherbroadcastaddr, ETHER_ADDR_LEN) == 0) { mbuf_free(m); return; } diff --git a/bsd/net/kpi_interface.c b/bsd/net/kpi_interface.c index a5d64adac..0ce0359ba 100644 --- a/bsd/net/kpi_interface.c +++ b/bsd/net/kpi_interface.c @@ -1073,8 +1073,14 @@ ifnet_find_by_name( ifnet_head_lock_shared(); TAILQ_FOREACH(ifp, &ifnet, if_link) { - struct sockaddr_dl *ll_addr = - (struct sockaddr_dl *)ifnet_addrs[ifp->if_index - 1]->ifa_addr; + struct ifaddr *ifa = ifnet_addrs[ifp->if_index - 1]; + struct sockaddr_dl *ll_addr; + + if (!ifa || !ifa->ifa_addr) + continue; + + ll_addr = (struct sockaddr_dl *)ifa->ifa_addr; + if ((ifp->if_eflags & IFEF_DETACHING) == 0 && namelen == ll_addr->sdl_nlen && (strncmp(ll_addr->sdl_data, ifname, ll_addr->sdl_nlen) == 0)) diff --git a/bsd/net/ndrv.c b/bsd/net/ndrv.c index 38429b2f1..ed973ec45 100644 --- a/bsd/net/ndrv.c +++ b/bsd/net/ndrv.c @@ -551,6 +551,9 @@ ndrv_do_detach(struct ndrv_cb *np) if (cur_np == NULL) { dlil_detach_protocol(np->nd_if, PF_NDRV); } + } else { + /* Remove from the linked list of control blocks */ + TAILQ_REMOVE(&ndrvl, np, nd_next); } FREE((caddr_t)np, M_PCB); diff --git a/bsd/netat/ddp_lap.c b/bsd/netat/ddp_lap.c index f2ed8d1b4..49e20d573 100644 --- a/bsd/netat/ddp_lap.c +++ b/bsd/netat/ddp_lap.c @@ -1193,7 +1193,7 @@ int ddp_shutdown(count_only) atalk_notify(gref, ESHUTDOWN); } } - if (count_only || active_skts) { + if (count_only) { splx(s); return(active_skts); diff --git a/bsd/netinet/ip_dummynet.c b/bsd/netinet/ip_dummynet.c index 013ccbf43..2b815370e 100644 --- a/bsd/netinet/ip_dummynet.c +++ b/bsd/netinet/ip_dummynet.c @@ -1177,12 +1177,13 @@ dummynet_io(struct mbuf *m, int pipe_nr, int dir, struct ip_fw_args *fwa) /* XXX expensive to zero, see if we can remove it*/ mtag = m_tag_alloc(KERNEL_MODULE_TAG_ID, KERNEL_TAG_TYPE_DUMMYNET, - sizeof(struct dn_pkt_tag), M_NOWAIT|M_ZERO); + sizeof(struct dn_pkt_tag), M_NOWAIT); if ( mtag == NULL ) goto dropit ; /* cannot allocate packet header */ m_tag_prepend(m, mtag); /* attach to mbuf chain */ pkt = (struct dn_pkt_tag *)(mtag+1); + bzero(pkt, sizeof(struct dn_pkt_tag)); /* ok, i can handle the pkt now... */ /* build and enqueue packet + parameters */ pkt->rule = fwa->rule ; diff --git a/bsd/netinet/ip_fw2.c b/bsd/netinet/ip_fw2.c index d2971587a..9801fb7d3 100644 --- a/bsd/netinet/ip_fw2.c +++ b/bsd/netinet/ip_fw2.c @@ -1304,6 +1304,7 @@ send_reject(struct ip_fw_args *args, int code, int offset, int ip_len) ip->ip_len = ntohs(ip->ip_len); ip->ip_off = ntohs(ip->ip_off); } + args->m->m_flags |= M_SKIP_FIREWALL; icmp_error(args->m, ICMP_UNREACH, code, 0L, 0); } else if (offset == 0 && args->f_id.proto == IPPROTO_TCP) { struct tcphdr *const tcp = diff --git a/bsd/netinet/ip_icmp.c b/bsd/netinet/ip_icmp.c index 3c858e783..030ef0680 100644 --- a/bsd/netinet/ip_icmp.c +++ b/bsd/netinet/ip_icmp.c @@ -89,6 +89,13 @@ #if defined(NFAITH) && NFAITH > 0 #include "faith.h" #include <net/if_types.h> +#endif + + /* XXX This one should go in sys/mbuf.h. It is used to avoid that + * a firewall-generated packet loops forever through the firewall. + */ +#ifndef M_SKIP_FIREWALL +#define M_SKIP_FIREWALL 0x4000 #endif /* @@ -200,6 +207,12 @@ icmp_error( m = m_gethdr(M_DONTWAIT, MT_HEADER); if (m == NULL) goto freeit; + + if (n->m_flags & M_SKIP_FIREWALL) { + /* set M_SKIP_FIREWALL to skip firewall check, since we're called from firewall */ + m->m_flags |= M_SKIP_FIREWALL; + } + icmplen = min(oiplen + 8, oip->ip_len); if (icmplen < sizeof(struct ip)) { printf("icmp_error: bad length\n"); diff --git a/bsd/netinet/ip_input.c b/bsd/netinet/ip_input.c index 96ad70ed7..f567de39e 100644 --- a/bsd/netinet/ip_input.c +++ b/bsd/netinet/ip_input.c @@ -2277,8 +2277,12 @@ ip_savecontrol( ifnet_head_lock_shared(); if (((ifp = m->m_pkthdr.rcvif)) && ( ifp->if_index && (ifp->if_index <= if_index))) { - sdp = (struct sockaddr_dl *)(ifnet_addrs - [ifp->if_index - 1]->ifa_addr); + struct ifaddr *ifa = ifnet_addrs[ifp->if_index - 1]; + + if (!ifa || !ifa->ifa_addr) + goto makedummy; + + sdp = (struct sockaddr_dl *)ifa->ifa_addr; /* * Change our mind and don't try copy. */ diff --git a/bsd/netinet6/ip6_forward.c b/bsd/netinet6/ip6_forward.c index d857cc307..4cb3871ad 100644 --- a/bsd/netinet6/ip6_forward.c +++ b/bsd/netinet6/ip6_forward.c @@ -273,7 +273,14 @@ ip6_forward(m, srcrt, locked) state.ro = NULL; /* update at ipsec6_output_tunnel() */ state.dst = NULL; /* update at ipsec6_output_tunnel() */ + if (locked) + lck_mtx_unlock(ip6_mutex); error = ipsec6_output_tunnel(&state, sp, 0); + if (locked) { + lck_mtx_unlock(sadb_mutex); + lck_mtx_lock(ip6_mutex); + lck_mtx_lock(sadb_mutex); + } m = state.m; key_freesp(sp); diff --git a/bsd/netinet6/ip6_output.c b/bsd/netinet6/ip6_output.c index c2bdcc28d..c8b578e6c 100644 --- a/bsd/netinet6/ip6_output.c +++ b/bsd/netinet6/ip6_output.c @@ -456,8 +456,12 @@ ip6_output( bzero(&state, sizeof(state)); state.m = m; + lck_mtx_unlock(ip6_mutex); + lck_mtx_lock(sadb_mutex); error = ipsec6_output_trans(&state, nexthdrp, mprev, sp, flags, &needipsectun); + lck_mtx_unlock(sadb_mutex); + lck_mtx_lock(ip6_mutex); m = state.m; if (error) { /* mbuf is already reclaimed in ipsec6_output_trans. */ @@ -583,10 +587,11 @@ skip_ipsec2:; state.m = m; state.ro = (struct route *)ro; state.dst = (struct sockaddr *)dst; - + lck_mtx_unlock(ip6_mutex); lck_mtx_lock(sadb_mutex); error = ipsec6_output_tunnel(&state, sp, flags); lck_mtx_unlock(sadb_mutex); + lck_mtx_lock(ip6_mutex); m = state.m; ro = (struct route_in6 *)state.ro; dst = (struct sockaddr_in6 *)state.dst; diff --git a/bsd/netinet6/ipsec.c b/bsd/netinet6/ipsec.c index 7d8f334fd..9d6201d6a 100644 --- a/bsd/netinet6/ipsec.c +++ b/bsd/netinet6/ipsec.c @@ -2904,7 +2904,7 @@ ipsec6_output_trans(state, nexthdrp, mprev, sp, flags, tun) printf("ipsec6_output_trans: applyed SP\n"); kdebug_secpolicy(sp)); - lck_mtx_lock(sadb_mutex); + lck_mtx_assert(sadb_mutex, LCK_MTX_ASSERT_OWNED); *tun = 0; for (isr = sp->req; isr; isr = isr->next) { if (isr->saidx.mode == IPSEC_MODE_TUNNEL) { @@ -2963,10 +2963,10 @@ ipsec6_output_trans(state, nexthdrp, mprev, sp, flags, tun) * XXX: should we directly notify sockets via * pfctlinputs? */ - lck_mtx_unlock(ip6_mutex); + lck_mtx_unlock(sadb_mutex); icmp6_error(state->m, ICMP6_DST_UNREACH, ICMP6_DST_UNREACH_ADMIN, 0); - lck_mtx_lock(ip6_mutex); + lck_mtx_lock(sadb_mutex); state->m = NULL; /* icmp6_error freed the mbuf */ goto bad; } @@ -3036,11 +3036,9 @@ ipsec6_output_trans(state, nexthdrp, mprev, sp, flags, tun) if (isr != NULL) *tun = 1; - lck_mtx_unlock(sadb_mutex); return 0; bad: - lck_mtx_unlock(sadb_mutex); m_freem(state->m); state->m = NULL; return error; diff --git a/bsd/nfs/nfs_vnops.c b/bsd/nfs/nfs_vnops.c index b5d0b9c6f..7704db2cb 100644 --- a/bsd/nfs/nfs_vnops.c +++ b/bsd/nfs/nfs_vnops.c @@ -4145,12 +4145,12 @@ again: goto again; } - if ((waitfor == MNT_WAIT) && !LIST_EMPTY(&np->n_dirtyblkhd)) { - goto again; - } - /* if we have no dirty blocks, we can clear the modified flag */ - if (LIST_EMPTY(&np->n_dirtyblkhd)) + if (waitfor == MNT_WAIT) { + if (!LIST_EMPTY(&np->n_dirtyblkhd)) + goto again; + /* if we have no dirty blocks, we can clear the modified flag */ np->n_flag &= ~NMODIFIED; + } FSDBG(526, np->n_flag, np->n_error, 0, 0); if (!ignore_writeerr && (np->n_flag & NWRITEERR)) { diff --git a/bsd/sys/file_internal.h b/bsd/sys/file_internal.h index 76dd19505..4656bab00 100644 --- a/bsd/sys/file_internal.h +++ b/bsd/sys/file_internal.h @@ -122,7 +122,8 @@ struct fileglob { int (*fo_write) __P((struct fileproc *fp, struct uio *uio, struct ucred *cred, int flags, struct proc *p)); -#define FOF_OFFSET 1 +#define FOF_OFFSET 0x00000001 /* offset supplied to vn_write */ +#define FOF_PCRED 0x00000002 /* cred from proc, not current thread */ int (*fo_ioctl) __P((struct fileproc *fp, u_long com, caddr_t data, struct proc *p)); int (*fo_select) __P((struct fileproc *fp, int which, diff --git a/bsd/sys/ubc.h b/bsd/sys/ubc.h index 46be17aa7..999cfb054 100644 --- a/bsd/sys/ubc.h +++ b/bsd/sys/ubc.h @@ -50,6 +50,8 @@ int ubc_setsize(struct vnode *, off_t); struct ucred *ubc_getcred(struct vnode *); int ubc_setcred(struct vnode *, struct proc *); +struct thread; +int ubc_setthreadcred(struct vnode *, struct proc *, struct thread *); int ubc_sync_range(vnode_t, off_t, off_t, int); errno_t ubc_msync(vnode_t, off_t, off_t, off_t *, int); diff --git a/bsd/ufs/ufs/ufs_vnops.c b/bsd/ufs/ufs/ufs_vnops.c index 9e4fe6eda..895610932 100644 --- a/bsd/ufs/ufs/ufs_vnops.c +++ b/bsd/ufs/ufs/ufs_vnops.c @@ -1491,10 +1491,19 @@ ufs_readdirext(vnode_t vp, uio_t uio, int *eofflag, int *numdirent, #if (BYTE_ORDER == LITTLE_ENDIAN) u_char tmp; - tmp = dp->d_namlen; - dp->d_namlen = dp->d_type; - dp->d_type = tmp; + /* + * We only need to swap the d_namlen and + * d_type fields for older versions of UFS, + * which we check by looking at the mnt_maxsymlinklen + * field. + */ + if (vp->v_mount->mnt_maxsymlinklen <= 0) { + tmp = dp->d_namlen; + dp->d_namlen = dp->d_type; + dp->d_type = tmp; + } #endif + xdp->d_reclen = EXT_DIRENT_LEN(dp->d_namlen); if (xdp->d_reclen > uio_resid(uio)) { break; /* user buffer is full */ @@ -1502,6 +1511,7 @@ ufs_readdirext(vnode_t vp, uio_t uio, int *eofflag, int *numdirent, xdp->d_ino = dp->d_ino; xdp->d_namlen = dp->d_namlen; xdp->d_type = dp->d_type; + bcopy(dp->d_name, xdp->d_name, dp->d_namlen + 1); off += dp->d_reclen; xdp->d_seekoff = off; diff --git a/bsd/vfs/vfs_utfconv.c b/bsd/vfs/vfs_utfconv.c index 01a49889e..11af9238a 100644 --- a/bsd/vfs/vfs_utfconv.c +++ b/bsd/vfs/vfs_utfconv.c @@ -117,10 +117,31 @@ unicode_decomposeable(u_int16_t character) { return (0); } + +/* + * Get the combing class. + * + * Similar to CFUniCharGetCombiningPropertyForCharacter. + */ +static inline u_int8_t +get_combining_class(u_int16_t character) { + const u_int8_t *bitmap = __CFUniCharCombiningPropertyBitmap; + + u_int8_t value = bitmap[(character >> 8)]; + + if (value) { + bitmap = bitmap + (value * 256); + return bitmap[character % 256]; + } + return (0); +} + + static int unicode_decompose(u_int16_t character, u_int16_t *convertedChars); static u_int16_t unicode_combine(u_int16_t base, u_int16_t combining); +static void priortysort(u_int16_t* characters, int count); char utf_extrabytes[32] = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, @@ -316,6 +337,7 @@ utf8_decodestr(const u_int8_t* utf8p, size_t utf8len, u_int16_t* ucsp, u_int16_t* bufend; unsigned int ucs_ch; unsigned int byte; + int combcharcnt = 0; int result = 0; int decompose, precompose, swapbytes; @@ -416,6 +438,7 @@ utf8_decodestr(const u_int8_t* utf8p, size_t utf8len, u_int16_t* ucsp, if (ucsp >= bufend) goto toolong; } + combcharcnt += count - 1; continue; } } else if (precompose && (ucsp != bufstart)) { @@ -436,8 +459,25 @@ utf8_decodestr(const u_int8_t* utf8p, size_t utf8len, u_int16_t* ucsp, if (ucs_ch == altslash) ucs_ch = '/'; + /* + * Make multiple combining character sequences canonical + */ + if (unicode_combinable(ucs_ch)) { + ++combcharcnt; /* start tracking a run */ + } else if (combcharcnt) { + if (combcharcnt > 1) { + priortysort(ucsp - combcharcnt, combcharcnt); + } + combcharcnt = 0; /* start over */ + } *ucsp++ = swapbytes ? NXSwapShort(ucs_ch) : ucs_ch; } + /* + * Make a previous combining sequence canonical + */ + if (combcharcnt > 1) { + priortysort(ucsp - combcharcnt, combcharcnt); + } exit: *ucslen = (u_int8_t*)ucsp - (u_int8_t*)bufstart; @@ -729,3 +769,39 @@ unicode_combine(u_int16_t base, u_int16_t combining) return (value); } + +/* + * priortysort - order combining chars into canonical order + * + * Similar to CFUniCharPrioritySort + */ +static void +priortysort(u_int16_t* characters, int count) +{ + u_int32_t p1, p2; + u_int16_t *ch1, *ch2; + u_int16_t *end; + int changes = 1; + + end = characters + count; + do { + changes = 0; + ch1 = characters; + ch2 = characters + 1; + p2 = get_combining_class(*ch1); + while (ch2 < end) { + p1 = p2; + p2 = get_combining_class(*ch2); + if (p1 > p2) { + u_int32_t tmp; + + tmp = *ch1; + *ch1 = *ch2; + *ch2 = tmp; + changes = 1; + } + ++ch1; + ++ch2; + } + } while (changes); +} diff --git a/bsd/vfs/vfs_utfconvdata.h b/bsd/vfs/vfs_utfconvdata.h index bc0c675fe..ec64223d9 100644 --- a/bsd/vfs/vfs_utfconvdata.h +++ b/bsd/vfs/vfs_utfconvdata.h @@ -1013,3 +1013,681 @@ __CFUniCharCombiningBitmap[] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }; + +static const u_int8_t +__CFUniCharCombiningPropertyBitmap[] = { + 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, + 0x00, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, + 0x0D, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0E, + 0x0F, 0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x12, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x13, 0x00, 0x00, 0x14, 0x00, + 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, + 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, + 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE8, 0xDC, 0xDC, + 0xDC, 0xDC, 0xE8, 0xD8, 0xDC, 0xDC, 0xDC, 0xDC, + 0xDC, 0xCA, 0xCA, 0xDC, 0xDC, 0xDC, 0xDC, 0xCA, + 0xCA, 0xDC, 0xDC, 0xDC, 0xDC, 0xDC, 0xDC, 0xDC, + 0xDC, 0xDC, 0xDC, 0xDC, 0x01, 0x01, 0x01, 0x01, + 0x01, 0xDC, 0xDC, 0xDC, 0xDC, 0xE6, 0xE6, 0xE6, + 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xF0, 0xE6, 0xDC, + 0xDC, 0xDC, 0xE6, 0xE6, 0xE6, 0xDC, 0xDC, 0x00, + 0xE6, 0xE6, 0xE6, 0xDC, 0xDC, 0xDC, 0xDC, 0xE6, + 0x00, 0x00, 0x00, 0x00, 0x00, 0xEA, 0xEA, 0xE9, + 0xEA, 0xEA, 0xE9, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, + 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0xE6, 0xE6, 0xE6, 0xE6, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0xDC, 0xE6, 0xE6, 0xE6, 0xE6, 0xDC, 0xE6, + 0xE6, 0xE6, 0xDE, 0xDC, 0xE6, 0xE6, 0xE6, 0xE6, + 0xE6, 0xE6, 0x00, 0xDC, 0xDC, 0xDC, 0xDC, 0xDC, + 0xE6, 0xE6, 0xDC, 0xE6, 0xE6, 0xDE, 0xE4, 0xE6, + 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10, 0x11, + 0x12, 0x13, 0x00, 0x14, 0x15, 0x16, 0x00, 0x17, + 0x00, 0x18, 0x19, 0x00, 0xE6, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F, + 0x20, 0x21, 0x22, 0xE6, 0xE6, 0xDC, 0xDC, 0xE6, + 0xE6, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x23, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xE6, 0xE6, + 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0x00, 0x00, 0xE6, + 0xE6, 0xE6, 0xE6, 0xDC, 0xE6, 0x00, 0x00, 0xE6, + 0xE6, 0x00, 0xDC, 0xE6, 0xE6, 0xDC, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x24, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0xE6, 0xDC, 0xE6, 0xE6, 0xDC, 0xE6, 0xE6, 0xDC, + 0xDC, 0xDC, 0xE6, 0xDC, 0xDC, 0xE6, 0xDC, 0xE6, + 0xE6, 0xE6, 0xDC, 0xE6, 0xDC, 0xE6, 0xDC, 0xE6, + 0xDC, 0xE6, 0xE6, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, + 0x00, 0xE6, 0xDC, 0xE6, 0xE6, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x54, 0x5B, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x67, 0x67, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x6B, 0x6B, 0x6B, 0x6B, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x76, 0x76, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x7A, 0x7A, 0x7A, 0x7A, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0xDC, 0xDC, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0xDC, 0x00, 0xDC, + 0x00, 0xD8, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x81, 0x82, 0x00, 0x84, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x82, 0x82, 0x82, 0x82, 0x00, 0x00, + 0x82, 0x00, 0xE6, 0xE6, 0x09, 0x00, 0xE6, 0xE6, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xDC, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x07, + 0x00, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0xE6, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0xE4, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0xDE, 0xE6, 0xDC, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0xE6, 0xE6, 0x01, 0x01, 0xE6, 0xE6, 0xE6, 0xE6, + 0x01, 0x01, 0x01, 0xE6, 0xE6, 0x00, 0x00, 0x00, + 0x00, 0xE6, 0x00, 0x00, 0x00, 0x01, 0x01, 0xE6, + 0xDC, 0xE6, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0xDA, 0xE4, 0xE8, 0xDE, 0xE0, 0xE0, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x08, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x1A, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0xE6, 0xE6, 0xE6, 0xE6, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 +}; + + diff --git a/bsd/vfs/vfs_vnops.c b/bsd/vfs/vfs_vnops.c index 3eb3f1522..402d876ea 100644 --- a/bsd/vfs/vfs_vnops.c +++ b/bsd/vfs/vfs_vnops.c @@ -600,7 +600,19 @@ vn_write(struct fileproc *fp, struct uio *uio, kauth_cred_t cred, * Set the credentials on successful writes */ if ((error == 0) && (vp->v_tag == VT_NFS) && (UBCINFOEXISTS(vp))) { - ubc_setcred(vp, p); + /* + * When called from aio subsystem, we only have the proc from + * which to get the credential, at this point, so use that + * instead. This means aio functions are incompatible with + * per-thread credentials (aio operations are proxied). We + * can't easily correct the aio vs. settid race in this case + * anyway, so we disallow it. + */ + if ((flags & FOF_PCRED) == 0) { + ubc_setthreadcred(vp, p, current_thread()); + } else { + ubc_setcred(vp, p); + } } (void)vnode_put(vp); return (error); diff --git a/bsd/vm/dp_backing_file.c b/bsd/vm/dp_backing_file.c index 56ff8efc9..92eb65eb9 100644 --- a/bsd/vm/dp_backing_file.c +++ b/bsd/vm/dp_backing_file.c @@ -269,7 +269,7 @@ macx_swapon( /* Mark this vnode as being used for swapfile */ SET(vp->v_flag, VSWAP); - ubc_setcred(vp, p); + ubc_setthreadcred(vp, p, current_thread()); /* * take a long term reference on the vnode to keep diff --git a/bsd/vm/vm_unix.c b/bsd/vm/vm_unix.c index 4dfe84ebb..f20fc6e2c 100644 --- a/bsd/vm/vm_unix.c +++ b/bsd/vm/vm_unix.c @@ -396,9 +396,13 @@ task_for_pid( if ( (p != (struct proc *) 0) && (p1 != (struct proc *) 0) - && (((kauth_cred_getuid(p->p_ucred) == kauth_cred_getuid(kauth_cred_get())) && - ((p->p_ucred->cr_ruid == kauth_cred_get()->cr_ruid))) - || !(suser(kauth_cred_get(), 0))) + && ( + (p1 == p) + || !(suser(kauth_cred_get(), 0)) + || ((kauth_cred_getuid(p->p_ucred) == kauth_cred_getuid(kauth_cred_get())) + && (p->p_ucred->cr_ruid == kauth_cred_get()->cr_ruid) + && ((p->p_flag & P_SUGID) == 0)) + ) && (p->p_stat != SZOMB) ) { if (p->task != TASK_NULL) { diff --git a/config/BSDKernel.exports b/config/BSDKernel.exports index 596e1bef0..eea8f21d8 100644 --- a/config/BSDKernel.exports +++ b/config/BSDKernel.exports @@ -596,6 +596,7 @@ _ubc_page_op _ubc_range_op _ubc_setcred _ubc_setsize +_ubc_setthreadcred _ubc_sync_range _ubc_upl_abort _ubc_upl_abort_range diff --git a/config/MasterVersion b/config/MasterVersion index bb78832f5..646e0cd0f 100644 --- a/config/MasterVersion +++ b/config/MasterVersion @@ -1,4 +1,4 @@ -8.6.0 +8.7.0 # The first line of this file contains the master version number for the kernel. # All other instances of the kernel version in xnu are derived from this file. diff --git a/iokit/bsddev/DINetBootHook.cpp b/iokit/bsddev/DINetBootHook.cpp index f80e35b35..9ba7b5b91 100644 --- a/iokit/bsddev/DINetBootHook.cpp +++ b/iokit/bsddev/DINetBootHook.cpp @@ -11,7 +11,7 @@ * Revision 1.3 2002/06/16 20:36:02 lindak * Merged PR-2957314 into Jaguar (siegmund: netboot kernel code needs to set * com.apple.AppleDiskImageController.load to boolean Yes) - * + * * Revision 1.2.40.2 2002/06/15 03:50:38 dieter * - corrected com.apple.AppleDiskImageController.load string * diff --git a/iokit/bsddev/DINetBootHook.h b/iokit/bsddev/DINetBootHook.h index b2936edfb..ed1f54381 100644 --- a/iokit/bsddev/DINetBootHook.h +++ b/iokit/bsddev/DINetBootHook.h @@ -14,7 +14,7 @@ * Changes from Josh(networking), Rick(IOKit), Jim & David(osfmk), Umesh, Dan & Ramesh(BSD) * Submitted by: Ramesh * Reviewed by: Vincent - * + * * Revision 1.2.12.1 2002/05/21 23:08:14 aramesh * Kernel API Cleanup * Bug #: 2853781 diff --git a/libkern/libkern/OSCrossEndian.h b/libkern/libkern/OSCrossEndian.h index 2d04f44d6..0131455d1 100644 --- a/libkern/libkern/OSCrossEndian.h +++ b/libkern/libkern/OSCrossEndian.h @@ -56,8 +56,14 @@ static __inline__ int _OSRosettaCheck(void) { - int isCrossEndian = 0; + int isCrossEndian; + __asm__ ( "b 0f\n" + " .long 0x14400004\n" + " li %0,1\n" + "0:" + : "=r" (isCrossEndian) : "0" (0) + ); return isCrossEndian; } diff --git a/osfmk/man/DMN_port_deleted.html b/osfmk/man/DMN_port_deleted.html index 357e0e008..becad9e6e 100755 --- a/osfmk/man/DMN_port_deleted.html +++ b/osfmk/man/DMN_port_deleted.html @@ -1 +1,65 @@ -<h2>do_mach_notify_port_deleted</h2> <hr> <p> <strong>Server Interface</strong> - Handle the current instance of a port-deleted notification. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t do_mach_notify_port_deleted</strong> <strong>(notify_port_t</strong> <var>notify</var>, <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> <strong>kern_return_t do_seqnos_mach_notify_port_deleted</strong> <strong>(notify_port_t</strong> <var>notify</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>notify</var> <dd> [in notify (receive) right] The port to which the notification was sent. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the notification port. <p> <dt> <var>name</var> <dd> [in scalar] The invalid name. </dl> <h3>DESCRIPTION</h3> <p> A <strong>do_mach_notify_port_deleted</strong> function is called by <strong>notify_server</strong> as the result of a kernel message indicating that a port name is no longer usable (that is, it no longer names a valid right), typically as a result of the right so named being consumed or moved. In contrast, a dead-name notification indicates that the port name is now dead as the result of the associated receive right having died. <var>notify</var> is the port named via <strong>mach_port_request_notification</strong> or <strong>mach_msg</strong>. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="notify_server.html"><strong>notify_server</strong></a>, <a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>, <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, <a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>, <a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>, <a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>. \ No newline at end of file +<h2>do_mach_notify_port_deleted</h2> +<hr> +<p> +<strong>Server Interface</strong> - Handle the current instance of a port-deleted notification. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t do_mach_notify_port_deleted</strong> + <strong>(notify_port_t</strong> <var>notify</var>, + <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> + + +<strong>kern_return_t do_seqnos_mach_notify_port_deleted</strong> + <strong>(notify_port_t</strong> <var>notify</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>notify</var> +<dd> +[in notify (receive) right] +The port to which the notification was sent. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the +notification port. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The invalid name. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>do_mach_notify_port_deleted</strong> function is called by +<strong>notify_server</strong> as the +result of a kernel message indicating that a port name is no +longer usable (that is, +it no longer names a valid right), typically as a result of the right so named +being consumed or moved. In contrast, a dead-name notification +indicates that the +port name is now dead as the result of the associated receive +right having died. +<var>notify</var> is the port named via <strong>mach_port_request_notification</strong> +or <strong>mach_msg</strong>. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="notify_server.html"><strong>notify_server</strong></a>, +<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>, +<a href="mach_msg.html"><strong>mach_msg</strong></a>, +<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, +<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>, +<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>, +<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>. diff --git a/osfmk/man/DMN_port_destroyed.html b/osfmk/man/DMN_port_destroyed.html index 9caab669c..ed1383891 100755 --- a/osfmk/man/DMN_port_destroyed.html +++ b/osfmk/man/DMN_port_destroyed.html @@ -1 +1,59 @@ -<h2>do_mach_notify_port_destroyed</h2> <hr> <p> <strong>Server Interface</strong> - Handle the current instance of a port-destroyed notification. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t do_mach_notify_port_destroyed</strong> <strong>(notify_port_t</strong> <var>notify</var>, <strong>mach_port_receive_t</strong> <var>name</var><strong>);</strong> <strong>kern_return_t do_seqnos_mach_notify_port_destroyed</strong> <strong>(mach_port_t</strong> <var>notify</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>mach_port_receive_t</strong> <var>name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>notify</var> <dd> [in notify (receive) right] The port to which the notification was sent. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the notification port. <p> <dt> <var>name</var> <dd> [in scalar] The invalid name. </dl> <h3>DESCRIPTION</h3> <p> A <strong>do_mach_notify_port_destroyed</strong> function is called by <strong>notify_server</strong> as the result of a kernel message indicating that a receive right would have been destroyed. <var>notify</var> is the port named via <strong>mach_port_request_notification</strong> or <strong>mach_msg</strong>. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="notify_server.html"><strong>notify_server</strong></a>, <a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>, <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, <a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>, <a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>, <a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>. \ No newline at end of file +<h2>do_mach_notify_port_destroyed</h2> +<hr> +<p> +<strong>Server Interface</strong> - Handle the current instance of a port-destroyed notification. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t do_mach_notify_port_destroyed</strong> + <strong>(notify_port_t</strong> <var>notify</var>, + <strong>mach_port_receive_t</strong> <var>name</var><strong>);</strong> + + +<strong>kern_return_t do_seqnos_mach_notify_port_destroyed</strong> + <strong>(mach_port_t</strong> <var>notify</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>mach_port_receive_t</strong> <var>name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>notify</var> +<dd> +[in notify (receive) right] +The port to which the notification was sent. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the +notification port. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The invalid name. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>do_mach_notify_port_destroyed</strong> function is called by +<strong>notify_server</strong> as the +result of a kernel message indicating that a receive right would have +been destroyed. <var>notify</var> is the port named via +<strong>mach_port_request_notification</strong> or <strong>mach_msg</strong>. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="notify_server.html"><strong>notify_server</strong></a>, +<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>, +<a href="mach_msg.html"><strong>mach_msg</strong></a>, +<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, +<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>, +<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>, +<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>. diff --git a/osfmk/man/DP_backing_store_create.html b/osfmk/man/DP_backing_store_create.html index ba58934eb..a0f76c8e4 100755 --- a/osfmk/man/DP_backing_store_create.html +++ b/osfmk/man/DP_backing_store_create.html @@ -1 +1,62 @@ -<h2>default_pager_backing_store_create</h2> <hr> <p> <strong>Server Interface</strong> - Create a backing storage object. <h3>SYNOPSIS</h3> <pre> <strong>#include< mach/default_pager_object.h></strong> <strong>kern_return_t default_pager_backing_store_create</strong> <strong>(mach_port_t</strong> <var>pager</var>, <strong>int</strong> <var>priority</var>, <strong>int</strong> <var>clsize</var>, <strong>mach_port_t</strong> <var>backing_store</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>pager</var> <dd> [in default pager (receive) right] The default pager service port. <p> <dt> <var>priority</var> <dd> [in scalar] The scheduling priority for the backing store service thread(s). <p> <dt> <var>clsize</var> <dd> [in scalar] The preferred cluster size (in bytes) for the backing store object. <p> <dt> <var>backing_store</var> <dd> [out backing store (receive) right] The port used to manipulate the created backing store. </dl> <h3>DESCRIPTION</h3> <p> The <strong>default_pager_backing_store_create</strong> function is called to create a new backing storage object. The kernel does not make this call itself (which is why it can be a synchronous call); this request is only issued by tasks (privileged) holding the default pager service port. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_FAILURE</strong> <dd> The default pager does not support this operation. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The pager port does not represent a valid default pager. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The operation was successful. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>, <a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>. \ No newline at end of file +<h2>default_pager_backing_store_create</h2> +<hr> +<p> +<strong>Server Interface</strong> - Create a backing storage object. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< mach/default_pager_object.h></strong> + +<strong>kern_return_t default_pager_backing_store_create</strong> + <strong>(mach_port_t</strong> <var>pager</var>, + <strong>int</strong> <var>priority</var>, + <strong>int</strong> <var>clsize</var>, + <strong>mach_port_t</strong> <var>backing_store</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>pager</var> +<dd> +[in default pager (receive) right] The default pager service port. +<p> +<dt> <var>priority</var> +<dd> +[in scalar] The scheduling priority for the backing store service +thread(s). +<p> +<dt> <var>clsize</var> +<dd> +[in scalar] The preferred cluster size (in bytes) for the backing +store object. +<p> +<dt> <var>backing_store</var> +<dd> +[out backing store (receive) right] The port used to manipulate the +created backing store. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>default_pager_backing_store_create</strong> function is called to create a +new backing storage object. The kernel does not make this call itself +(which is why it can be a synchronous call); this request is only +issued by tasks (privileged) holding the default pager service port. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_FAILURE</strong> +<dd> +The default pager does not support this operation. +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The pager port does not represent a valid default pager. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The operation was successful. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>, +<a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>. diff --git a/osfmk/man/DP_backing_store_delete.html b/osfmk/man/DP_backing_store_delete.html index a4018cb6a..0d63818bd 100755 --- a/osfmk/man/DP_backing_store_delete.html +++ b/osfmk/man/DP_backing_store_delete.html @@ -1 +1,48 @@ -<h2>default_pager_backing_store_delete</h2> <hr> <p> <strong>Server Interface</strong> - Delete a backing storage object. <h3>SYNOPSIS</h3> <pre> <strong>#include< mach/default_pager_object.h></strong> <strong>kern_return_t default_pager_backing_store_delete</strong> <strong>(mach_port_t</strong> <var>backing_store</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>backing_store</var> <dd> [in backing store (receive) right] The backing store port created by default_pager_backing_store_create. </dl> <h3>DESCRIPTION</h3> <p> The <strong>default_pager_backing_store_delete</strong> function is called to destroy a backing storage object created by <strong>default_pager_backing_store_create</strong>. The kernel does not make this call itself (which is why it can be a synchronous call); this request is only issued by tasks holding the backing store port, created with <strong>default_pager_backing_store_create</strong>, for a default memory manager. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_FAILURE</strong> <dd> The default pager does not support this operation. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The backing_store port does not represent a valid backing store or the specified segment overlaps an existing partition. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The operation was successful. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>, <a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>. \ No newline at end of file +<h2>default_pager_backing_store_delete</h2> +<hr> +<p> +<strong>Server Interface</strong> - Delete a backing storage object. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< mach/default_pager_object.h></strong> + +<strong>kern_return_t default_pager_backing_store_delete</strong> + <strong>(mach_port_t</strong> <var>backing_store</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>backing_store</var> +<dd> +[in backing store (receive) right] The backing store port created by +default_pager_backing_store_create. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>default_pager_backing_store_delete</strong> function is called to destroy a +backing storage object created by +<strong>default_pager_backing_store_create</strong>. The kernel does not make this call +itself (which is why it can be a synchronous call); this request is +only issued by tasks holding the backing store port, created with +<strong>default_pager_backing_store_create</strong>, for a default memory manager. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_FAILURE</strong> +<dd> +The default pager does not support this operation. +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The backing_store port does not represent a valid backing store or the +specified segment overlaps an existing partition. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The operation was successful. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>, +<a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>. diff --git a/osfmk/man/DP_backing_store_info.html b/osfmk/man/DP_backing_store_info.html index 21da7ae5c..10934cfbd 100755 --- a/osfmk/man/DP_backing_store_info.html +++ b/osfmk/man/DP_backing_store_info.html @@ -1 +1,74 @@ -<h2>default_pager_backing_store_info</h2> <hr> <p> <strong>Server Interface</strong> - Return information about a backing storage object. <h3>SYNOPSIS</h3> <pre> <strong>#include< default_pager/mach/default_pager_types.h></strong> <strong>kern_return_t default_pager_backing_store_info</strong> <strong>(mach_port_t</strong> <var>backing_store</var>, <strong>backing_store_flavor_t</strong> <var>flavor</var>, <strong>backing_store_info_t</strong> <var>info</var>, <strong>mach_msg_type_number_t</strong> <var>size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>backing_store</var> <dd> [in backing store (receive) right] The backing store port for which information is desired. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of information to be returned. Valid values are: <p> <dt> <var>BACKING_STORE_BASIC_INFO</var> <dd> Statistical and space used/available information. It includes the priority and cluster size that was provided in the default_pager_backing_store_create call. <p> <dt> <var>info</var> <dd> [pointer to in structure] The data structure that will be filled in with the information provided for the requested flavor. <p> <dt> <var>size</var> <dd> [pointer to in/out scalar] On input, the maximum size of the info data structure; on output, the actual size of the returned data. </dl> <h3>DESCRIPTION</h3> <p> The <strong>default_pager_backing_store_info</strong> function is called to obtain information about a backing storage object created by <strong>default_pager_backing_store_create</strong>. The kernel does not make this call itself (which is why it can be a synchronous call); this request is only issued by tasks holding the backing store port, created with <strong>default_pager_backing_store_create</strong>, for a default memory manager. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_FAILURE</strong> <dd> The default pager does not support this operation. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The backing_store port does not represent a valid backing store, flavor is not valid, or size is not the size for the requested flavor. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The operation was successful. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>, <a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>. <p> Data Structures: backing_store_basic_info. \ No newline at end of file +<h2>default_pager_backing_store_info</h2> +<hr> +<p> +<strong>Server Interface</strong> - Return information about a backing storage object. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< default_pager/mach/default_pager_types.h></strong> + +<strong>kern_return_t default_pager_backing_store_info</strong> + <strong>(mach_port_t</strong> <var>backing_store</var>, + <strong>backing_store_flavor_t</strong> <var>flavor</var>, + <strong>backing_store_info_t</strong> <var>info</var>, + <strong>mach_msg_type_number_t</strong> <var>size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>backing_store</var> +<dd> +[in backing store (receive) right] The backing store port for which +information is desired. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] The type of information to be returned. Valid values are: +<p> +<dt> <var>BACKING_STORE_BASIC_INFO</var> +<dd> +Statistical and space used/available information. It includes +the priority and cluster size that was provided in the +default_pager_backing_store_create call. +<p> +<dt> <var>info</var> +<dd> +[pointer to in structure] The data structure that will be filled in with the +information provided for the requested flavor. +<p> +<dt> <var>size</var> +<dd> +[pointer to in/out scalar] On input, the maximum size of the info data +structure; on output, the actual size of the returned data. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>default_pager_backing_store_info</strong> function is called to obtain +information about a backing storage object created by +<strong>default_pager_backing_store_create</strong>. The kernel does not make this call +itself (which is why it can be a synchronous call); this request is +only issued by tasks holding the backing store port, created with +<strong>default_pager_backing_store_create</strong>, for a default memory manager. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_FAILURE</strong> +<dd> +The default pager does not support this operation. +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The backing_store port does not represent a valid backing store, flavor +is not valid, or size is not the size for the requested flavor. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The operation was successful. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>, +<a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>. +<p> +Data Structures: +backing_store_basic_info. diff --git a/osfmk/man/DP_object_create.html b/osfmk/man/DP_object_create.html index 9f94b814a..597b4e886 100755 --- a/osfmk/man/DP_object_create.html +++ b/osfmk/man/DP_object_create.html @@ -1 +1,72 @@ -<h2>default_pager_object_create</h2> <hr> <p> <strong>Server Interface</strong> - Initialize a non-persistent memory object suitable for sharing between tasks. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t default_pager_object_create</strong> <strong>(mach_port_t</strong> <var>pager</var>, <strong>memory_object_t</strong> <var>*memory_object</var>, <strong>vm_size_t</strong> <var>object_size</var><strong>);</strong> <strong>kern_return_t seqnos_default_pager_object_create</strong> <strong>(mach_port_t</strong> <var>pager</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_t</strong> <var>*memory_object</var>, <strong>vm_size_t</strong> <var>object_size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>pager</var> <dd> [in default-pager (receive) right] The default memory manager service port. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the <var>pager</var> port. <p> <dt> <var>memory_object</var> <dd> [out memory-object send right] A memory object port (with full access) for the memory object. <p> <dt> <var>object_size</var> <dd> [in scalar] The maximum size for the memory object. </dl> <h3>DESCRIPTION</h3> <p> A <strong>default_pager_object_create</strong> function is called as the result of a message requesting that the default memory manager create and return a (shared) memory object which is suitable for use with <strong>vm_map</strong>. This memory object has the same properties as does a memory object provided by <strong>vm_allocate</strong>: its initial contents are zero and the backing contents are temporary in that they do not persist after the memory object is destroyed. The memory object is suitable for use as non-permanent shared memory. The kernel does not make this call itself (which is why it can be a synchronous call); this request is only issued by (privileged) tasks holding the default memory manager port. This call should be contrasted with the kernel's <strong>memory_object_create</strong> message, in which the memory cache object is already created and the identity of the abstract memory object is made known to the default manager. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_map.html"><strong>vm_map</strong></a>, <a href="HD_memory_manager.html"><strong>host_default_memory_manager</strong></a>, <a href="memory_object_create.html"><strong>memory_object_create</strong></a>, <a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>, <a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>. \ No newline at end of file +<h2>default_pager_object_create</h2> +<hr> +<p> +<strong>Server Interface</strong> - Initialize a non-persistent memory object suitable for sharing between tasks. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t default_pager_object_create</strong> + <strong>(mach_port_t</strong> <var>pager</var>, + <strong>memory_object_t</strong> <var>*memory_object</var>, + <strong>vm_size_t</strong> <var>object_size</var><strong>);</strong> + + +<strong>kern_return_t seqnos_default_pager_object_create</strong> + <strong>(mach_port_t</strong> <var>pager</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_t</strong> <var>*memory_object</var>, + <strong>vm_size_t</strong> <var>object_size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>pager</var> +<dd> +[in default-pager (receive) right] +The default memory manager service +port. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the <var>pager</var> +port. +<p> +<dt> <var>memory_object</var> +<dd> +[out memory-object send right] +A memory object port (with full access) for the memory object. +<p> +<dt> <var>object_size</var> +<dd> +[in scalar] +The maximum size for the memory object. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>default_pager_object_create</strong> function is called as +the result of a message +requesting that the default memory manager create and return a (shared) memory +object which is suitable for use with <strong>vm_map</strong>. This memory object has +the same properties as does a memory object provided by +<strong>vm_allocate</strong>: its initial +contents are zero and the backing contents are temporary in that they do not +persist after the memory object is destroyed. The memory object +is suitable for use +as non-permanent shared memory. The kernel does not make this call itself +(which is why it can be a synchronous call); this request is only issued by +(privileged) tasks holding the default memory manager port. +This call should be +contrasted with the kernel's <strong>memory_object_create</strong> message, in which +the memory cache object is already created and the identity of the abstract +memory object is made known to the default manager. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_map.html"><strong>vm_map</strong></a>, +<a href="HD_memory_manager.html"><strong>host_default_memory_manager</strong></a>, +<a href="memory_object_create.html"><strong>memory_object_create</strong></a>, +<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>, +<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>. diff --git a/osfmk/man/DR_overwrite_async.html b/osfmk/man/DR_overwrite_async.html index a583d9b58..de8b0814a 100755 --- a/osfmk/man/DR_overwrite_async.html +++ b/osfmk/man/DR_overwrite_async.html @@ -1 +1,71 @@ -<h2>device_read_overwrite_async</h2> <hr> <p> <strong>System Trap</strong> - Read a sequence of bytes from a device object into the caller's <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t device_read_overwrite_async</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>queue</var>, <strong>mach_port_t</strong> <var>request_id</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var>, <strong>io_buf_ptr_t</strong> <var>buffer</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be read. <p> <dt> <var>queue</var> <dd> [in io_done queue send right] The port returned from the io_done_queue_create call. <p> <dt> <var>request_id</var> <dd> [in send right] An unique request identifier that will be passed back as part of the io_done_result structure. <p> <dt> <var>mode</var> <dd> [in scalar] I/O mode value. Meaningful options are: <p> <dl> <dt> <strong>D_NOWAIT</strong> <dd> Do not wait if data is unavailable. <p> </dl> <dt> <var>recnum</var> <dd> [in scalar] Record number to be read. <p> <dt> <var>bytes_wanted</var> <dd> [in scalar] Size of data transfer. <p> <dt> <var>buffer</var> <dd> [pointer to in array of bytes] Data buffer to be overwritten. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_read_overwrite</strong> system trap enqueues a read operation for a sequence of bytes from a device object to be placed directly into the caller's address space. The meaning of recnum as well as the specific operation performed is device dependent. <h3>RETURN VALUES</h3> <p> <strong>device_read_overwrite_async</strong> returns only invalid parameter errors. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_read_async.html"><strong>device_read_async</strong></a>, <a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, <a href="device_write_async.html"><strong>device_write_async</strong></a>, <a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>, <a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>. \ No newline at end of file +<h2>device_read_overwrite_async</h2> +<hr> +<p> +<strong>System Trap</strong> - Read a sequence of bytes from a device object into the caller's +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t device_read_overwrite_async</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>queue</var>, + <strong>mach_port_t</strong> <var>request_id</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var>, + <strong>io_buf_ptr_t</strong> <var>buffer</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] A device port to the device to be read. +<p> +<dt> <var>queue</var> +<dd> +[in io_done queue send right] The port returned from the +io_done_queue_create call. +<p> +<dt> <var>request_id</var> +<dd> +[in send right] An unique request identifier that will be passed back as +part of the io_done_result structure. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] I/O mode value. Meaningful options are: +<p> + <dl> +<dt> <strong>D_NOWAIT</strong> +<dd> +Do not wait if data is unavailable. +<p> + </dl> +<dt> <var>recnum</var> +<dd> +[in scalar] Record number to be read. +<p> +<dt> <var>bytes_wanted</var> +<dd> +[in scalar] Size of data transfer. +<p> +<dt> <var>buffer</var> +<dd> +[pointer to in array of bytes] Data buffer to be overwritten. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_read_overwrite</strong> system trap enqueues a read operation for a +sequence of bytes from a device object to be placed directly into +the caller's address space. The meaning of recnum as well as the +specific operation performed is device dependent. +<h3>RETURN VALUES</h3> +<p> +<strong>device_read_overwrite_async</strong> returns only invalid parameter errors. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_read_async.html"><strong>device_read_async</strong></a>, +<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, +<a href="device_write_async.html"><strong>device_write_async</strong></a>, +<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>, +<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>. diff --git a/osfmk/man/HD_memory_manager.html b/osfmk/man/HD_memory_manager.html index 36a1b5ea1..ff83a5004 100755 --- a/osfmk/man/HD_memory_manager.html +++ b/osfmk/man/HD_memory_manager.html @@ -1 +1,47 @@ -<h2>host_default_memory_manager</h2> <hr> <p> <strong>Function</strong> - Establish the official connection between the kernel and its default pager task. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_default_memory_manager</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>mach_port_make_send_t</strong> <var>default_manager</var>, <strong>vm_size_t</strong> <var>cluster_size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control send right] The control port naming the host for which the default memory manager is to be set. <p> <dt> <var>default_manager</var> <dd> [pointer to in/out default-pager send right] A memory manager port to the new default memory manager. If this value is <strong>MACH_PORT_NULL</strong>, the old memory manager is not changed. The old memory manager port is returned in this variable. <p> <dt> <var>cluster_size</var> <dd> [in scalar] The preferred cluster size (in bytes) for temporary memory objects. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_default_memory_manager</strong> function establishes the default memory manager for a host. The named manager will be the target for future <strong>memory_object_create</strong> calls. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_create.html"><strong>memory_object_create</strong></a>, <a href="vm_allocate.html"><strong>vm_allocate</strong></a>. \ No newline at end of file +<h2>host_default_memory_manager</h2> +<hr> +<p> +<strong>Function</strong> - Establish the official connection between the kernel and its default pager task. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_default_memory_manager</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>mach_port_make_send_t</strong> <var>default_manager</var>, + <strong>vm_size_t</strong> <var>cluster_size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The control port naming the host for which +the default memory manager is to be set. +<p> +<dt> <var>default_manager</var> +<dd> +[pointer to in/out default-pager send right] +A memory manager port to +the new default memory manager. If this value is <strong>MACH_PORT_NULL</strong>, +the old memory manager is not changed. The old memory +manager port is returned in this variable. +<p> +<dt> <var>cluster_size</var> +<dd> +[in scalar] +The preferred cluster size (in bytes) for temporary memory +objects. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_default_memory_manager</strong> function establishes the default +memory manager for a host. The named manager will be the target for future +<strong>memory_object_create</strong> calls. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_create.html"><strong>memory_object_create</strong></a>, +<a href="vm_allocate.html"><strong>vm_allocate</strong></a>. diff --git a/osfmk/man/MO_SY_completed.html b/osfmk/man/MO_SY_completed.html index da5828394..83c866920 100755 --- a/osfmk/man/MO_SY_completed.html +++ b/osfmk/man/MO_SY_completed.html @@ -1 +1,50 @@ -<h2>memory_object_synchronize_completed</h2> <hr> <p> <strong>Function</strong> - Inform the kernel that synchronized data has been processed. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_synchronize_completed </strong> <strong>(memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_offset_t</strong> <var>length</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used by the memory manager for cache management requests. This port is provided by the kernel in a <strong>memory_object_init</strong> call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object, in bytes. <p> <dt> <var>length</var> <dd> [in scalar] The amount of data processed. The number must be an integral number of memory object pages. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_synchronize_completed</strong> function informs the kernel that previously synchronized data (<strong>memory_object_synchronize</strong>) has been queued or placed on backing storage. This reply causes the issuing client to return from its <strong>vm_msync</strong> call. The offset and length must match that of the corresponding <strong>memory_object_synchronize</strong> call. There may be multiple synchronize requests for a given memory object outstanding but they will not overlap. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>, <a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>, <a href="vm_msync.html"><strong>vm_msync</strong></a>. \ No newline at end of file +<h2>memory_object_synchronize_completed</h2> +<hr> +<p> +<strong>Function</strong> - Inform the kernel that synchronized data has been processed. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_synchronize_completed </strong> + <strong>(memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_offset_t</strong> <var>length</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used by the memory manager for cache management requests. +This port is provided by the kernel in a <strong>memory_object_init</strong> call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object, in bytes. +<p> +<dt> <var>length</var> +<dd> +[in scalar] +The amount of data processed. The number must be an +integral number of memory object pages. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_synchronize_completed</strong> function informs the kernel +that previously synchronized data (<strong>memory_object_synchronize</strong>) +has been queued or placed on backing storage. This reply causes the issuing +client to return from its <strong>vm_msync</strong> call. The offset and length +must match that of the corresponding <strong>memory_object_synchronize</strong> +call. There may be multiple synchronize requests +for a given memory object outstanding but they will not overlap. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>, +<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>, +<a href="vm_msync.html"><strong>vm_msync</strong></a>. diff --git a/osfmk/man/MO_change_attributes.html b/osfmk/man/MO_change_attributes.html index 1bca01076..26f2b4f5a 100755 --- a/osfmk/man/MO_change_attributes.html +++ b/osfmk/man/MO_change_attributes.html @@ -1 +1,88 @@ -<h2>memory_object_change_attributes</h2> <hr> <p> <strong>Function</strong> - Modify caller-specified subset of attributes representing target memory object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_change_attributes</strong> <strong>(memory_object_control_t</strong> <var>memory_control</var>, <strong>memory_object_flavor_t</strong> <var>flavor</var>, <strong>memory_object_info_t</strong> <var>attributes</var>, <strong>attributes</strong> <var>attributes_count</var>, <strong>mach_port_t</strong> <var>reply_to</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used by the memory manager for cache management requests. This port is provided by the kernel in a <strong>memory_object_init</strong> or <strong>memory_object_create</strong> call. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of information to be changed. Valid values are: <dl> <p> <dt> <strong>MEMORY_OBJECT_PERFORMANCE_INFO</strong> <dd> Performance related attributes such as the cache indicator and the cluster size. <var>attributes</var> should specify a structure of type <strong>memory_object_perf_info</strong>. <p> <dt> <strong>MEMORY_OBJECT_BEHAVIOR_INFO</strong> <dd> Behavior related attributes such as the copy strategy and sync invalidate flag. <var>attributes</var> should specify a structure of type <strong>memory_object_behavior_info</strong>. <p> <dt> <strong>MEMORY_OBJECT_ATTRIBUTES_INFO</strong> <dd> Behavior and performance related attributes such as the copy strategy, cache indicator, and cluster size. <var>attributes</var> should specify a structure of type <strong>memory_object_attr_info</strong>. </dl> <p> <dt> <var>attributes</var> <dd> [pointer to in structure] New attributes. <p> <dt> <var>attributes_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). <p> <dt> <var>reply_port</var> <dd> [in reply receive (to be converted to send) right] A port to which a reply (<strong>memory_object_change_completed</strong>) is to be sent indicating the completion of the attribute change. Such a reply would be useful if the cache attribute is turned off, since such a change, if the memory object is no longer mapped, may result in the object being terminated. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_change_attributes</strong> function sets various attributes of the specified memory object. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="MO_change_completed.html"><strong>memory_object_change_completed</strong></a>, <a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>, <a href="memory_object_create.html"><strong>memory_object_create</strong></a>. <p> Data Structures: <a href="memory_object_perf_info.html"><strong>memory_object_perf_info</strong></a>, <a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>. \ No newline at end of file +<h2>memory_object_change_attributes</h2> +<hr> +<p> +<strong>Function</strong> - Modify caller-specified subset of attributes representing target memory object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_change_attributes</strong> + <strong>(memory_object_control_t</strong> <var>memory_control</var>, + <strong>memory_object_flavor_t</strong> <var>flavor</var>, + <strong>memory_object_info_t</strong> <var>attributes</var>, + <strong>attributes</strong> <var>attributes_count</var>, + <strong>mach_port_t</strong> <var>reply_to</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used by the memory manager for cache management requests. +This port is provided by the kernel in a <strong>memory_object_init</strong> + or <strong>memory_object_create</strong> call. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of information to be changed. Valid values are: +<dl> +<p> +<dt> <strong>MEMORY_OBJECT_PERFORMANCE_INFO</strong> +<dd> +Performance related attributes such as the cache indicator and +the cluster size. <var>attributes</var> should specify a structure of type +<strong>memory_object_perf_info</strong>. +<p> +<dt> <strong>MEMORY_OBJECT_BEHAVIOR_INFO</strong> +<dd> +Behavior related attributes such as the copy strategy and sync +invalidate flag. <var>attributes</var> should specify a structure of type +<strong>memory_object_behavior_info</strong>. +<p> +<dt> <strong>MEMORY_OBJECT_ATTRIBUTES_INFO</strong> +<dd> +Behavior and performance related attributes such as the copy strategy, +cache indicator, and cluster size. <var>attributes</var> should specify a structure of type +<strong>memory_object_attr_info</strong>. +</dl> +<p> +<dt> <var>attributes</var> +<dd> +[pointer to in structure] +New attributes. +<p> +<dt> <var>attributes_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +<p> +<dt> <var>reply_port</var> +<dd> +[in reply receive (to be converted to send) right] +A port to which a +reply (<strong>memory_object_change_completed</strong>) is to be sent indicating the +completion of the attribute change. Such a reply would be useful if the +cache attribute is turned off, since such a change, if the memory object +is no longer mapped, may result in the object being terminated. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_change_attributes</strong> function sets various +attributes of the +specified memory object. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="MO_change_completed.html"><strong>memory_object_change_completed</strong></a>, +<a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>, +<a href="memory_object_create.html"><strong>memory_object_create</strong></a>. +<p> +Data Structures: +<a href="memory_object_perf_info.html"><strong>memory_object_perf_info</strong></a>, +<a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>. + + diff --git a/osfmk/man/MO_change_completed.html b/osfmk/man/MO_change_completed.html index 51ec47a8a..cfdecc248 100755 --- a/osfmk/man/MO_change_completed.html +++ b/osfmk/man/MO_change_completed.html @@ -1 +1,67 @@ -<h2>memory_object_change_completed</h2> <hr> <p> <strong>Server Interface</strong> - Notify memory manager that kernel has updated memory object attributes as requested. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_change_completed</strong> <strong>(memory_object_t</strong> <var>reply_port</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>memory_object_flavor_t</strong> <var>flavor</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_change_completed</strong> <strong>(memory_object_t</strong> <var>reply_port</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>memory_object_flavor_t</strong> <var>flavor</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>reply_port</var> <dd> [in reply (receive) right] The port supplied in the corresponding <strong>memory_object_change_attributes</strong> call. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the port named in the <strong>memory_object_change_attributes</strong> call. <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used for a response by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. <p> <dt> <var>flavor</var> <dd> [in scalar] The flavor of attributes changed by the corresponding <strong>memory_object_change_attributes</strong> call. </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_change_completed</strong> function is called as the result of a kernel message confirming the kernel's action in response to a <strong>memory_object_change_attributes</strong> call from the memory manager. <p> When the kernel completes the requested changes, it calls <strong>memory_object_change_completed</strong> (asynchronously) using the port explicitly provided in the <strong>memory_object_change_attributes</strong> call. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>, <a href="memory_object_server.html"><strong>memory_object_server</strong></a>, <a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. \ No newline at end of file +<h2>memory_object_change_completed</h2> +<hr> +<p> +<strong>Server Interface</strong> - Notify memory manager that kernel has updated memory object attributes as requested. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_change_completed</strong> + <strong>(memory_object_t</strong> <var>reply_port</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>memory_object_flavor_t</strong> <var>flavor</var><strong>);</strong> + + +<strong>kern_return_t seqnos_memory_object_change_completed</strong> + <strong>(memory_object_t</strong> <var>reply_port</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>memory_object_flavor_t</strong> <var>flavor</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>reply_port</var> +<dd> +[in reply (receive) right] +The port supplied in the corresponding +<strong>memory_object_change_attributes</strong> call. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the port +named in the <strong>memory_object_change_attributes</strong> call. +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used for a response by the memory manager. If the memory +object has been supplied to more than one kernel, this parameter +identifies the kernel that is making the call. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The flavor of attributes changed by the corresponding +<strong>memory_object_change_attributes</strong> call. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_change_completed</strong> function is called +as the result of a +kernel message confirming the kernel's action in response to a +<strong>memory_object_change_attributes</strong> call from the memory manager. +<p> +When the kernel completes the requested changes, it calls +<strong>memory_object_change_completed</strong> (asynchronously) using +the port explicitly provided in +the <strong>memory_object_change_attributes</strong> call. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>, +<a href="memory_object_server.html"><strong>memory_object_server</strong></a>, +<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. diff --git a/osfmk/man/MO_data_initialize.html b/osfmk/man/MO_data_initialize.html index e391ae77f..d92bf9cf2 100755 --- a/osfmk/man/MO_data_initialize.html +++ b/osfmk/man/MO_data_initialize.html @@ -1 +1,79 @@ -<h2>memory_object_data_initialize</h2> <hr> <p> <strong>Server Interface</strong> - Request that the default pager record initialization information for specified memory object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_data_initialize</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>pointer_t</strong> <var>data</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_data_initialize</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>pointer_t</strong> <var>data</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_object</var> <dd> [in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data, as supplied by the kernel in a <strong>memory_object_create</strong> call. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the abstract memory object port. <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used for a response by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object. <p> <dt> <var>data</var> <dd> [in pointer to dynamic array of bytes] The data that has been modified while cached in physical memory. </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_data_initialize</strong> function is called as the result of a kernel message providing the default memory manager with initial data for a kernel-created memory object. If the memory manager already has supplied data (by a previous <strong>memory_object_data_initialize</strong> or <strong>memory_object_data_return</strong>), it should ignore this call. Otherwise, the call behaves the same as the <strong>memory_object_data_return</strong> call. <p> The kernel makes this call only to the default memory manager and only on temporary memory objects that it has created with <strong>memory_object_create</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_create.html"><strong>memory_object_create</strong></a>, <a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>, <a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>, <a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>. \ No newline at end of file +<h2>memory_object_data_initialize</h2> +<hr> +<p> +<strong>Server Interface</strong> - Request that the default pager record initialization information for specified memory object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_data_initialize</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>pointer_t</strong> <var>data</var><strong>);</strong> + + +<strong>kern_return_t seqnos_memory_object_data_initialize</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>pointer_t</strong> <var>data</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_object</var> +<dd> +[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data, as supplied by the +kernel in a <strong>memory_object_create</strong> call. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the abstract +memory object port. +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used for a response by the memory manager. If the memory +object has been supplied to more than one kernel, this parameter +identifies the kernel that is making the call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object. +<p> +<dt> <var>data</var> +<dd> +[in pointer to dynamic array of bytes] +The data that has been modified +while cached in physical memory. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_data_initialize</strong> function is called +as the result of a kernel +message providing the default memory manager with initial data for a +kernel-created memory object. If the memory manager already +has supplied data (by a previous <strong>memory_object_data_initialize</strong> or +<strong>memory_object_data_return</strong>), it +should ignore this call. Otherwise, the call behaves the same as the +<strong>memory_object_data_return</strong> call. +<p> +The kernel makes this call only to the default memory manager and only on +temporary memory objects that it has created with +<strong>memory_object_create</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_create.html"><strong>memory_object_create</strong></a>, +<a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>, +<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>, +<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>. diff --git a/osfmk/man/MO_data_unavailable.html b/osfmk/man/MO_data_unavailable.html index d74aeca7d..a65fe4382 100755 --- a/osfmk/man/MO_data_unavailable.html +++ b/osfmk/man/MO_data_unavailable.html @@ -1 +1,67 @@ -<h2>memory_object_data_unavailable</h2> <hr> <p> <strong>Function</strong> - Instruct kernel to zero-fill pages as requested data does not exist. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_data_unavailable</strong> <strong>(memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used by the memory manager for cache management requests. This port is provided by the kernel in a <strong>memory_object_init</strong> or a <strong>memory_object_create</strong> call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object, in bytes. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes of data (starting at <var>offset</var>). The number must convert to an integral number of memory object pages. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_data_unavailable</strong> function indicates that the memory manager cannot provide the kernel with the data requested for the given region. Instead, the kernel should provide the data for this region. <p> A memory manager can use this call in any of the following situations: <ul> <li> When the object was created by the kernel (via <strong>memory_object_create</strong>) and the kernel has not yet provided data for the region (via either <strong>memory_object_data_initialize</strong> or <strong>memory_object_data_return</strong>). In this case, the object is a temporary memory object; the memory manager is the default memory manager; and the kernel should provide zero-filled pages for the object. <p> <li> When the object is a normal user-created memory object. In this case, the kernel should provide zero-filled pages for the region. </ul> <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_create.html"><strong>memory_object_create</strong></a>, <a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>, <a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>, <a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>. \ No newline at end of file +<h2>memory_object_data_unavailable</h2> +<hr> +<p> +<strong>Function</strong> - Instruct kernel to zero-fill pages as requested data does not exist. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_data_unavailable</strong> + <strong>(memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used by the memory manager for cache management requests. +This port is provided by the kernel in a <strong>memory_object_init</strong> or a +<strong>memory_object_create</strong> call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object, in bytes. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes of data (starting at <var>offset</var>). The number +must convert to an integral number of memory object pages. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_data_unavailable</strong> function indicates +that the memory +manager cannot provide the kernel with the data requested for +the given region. +Instead, the kernel should provide the data for this region. +<p> +A memory manager can use this call in any of the following situations: +<ul> +<li> +When the object was created by the kernel +(via <strong>memory_object_create</strong>) and +the kernel has not yet provided data for the region (via either +<strong>memory_object_data_initialize</strong> or <strong>memory_object_data_return</strong>). +In this case, the +object is a temporary memory object; the memory manager is the default +memory manager; and the kernel should provide zero-filled pages for the +object. + <p> +<li> +When the object is a normal user-created memory object. In this case, the +kernel should provide zero-filled pages for the region. +</ul> +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_create.html"><strong>memory_object_create</strong></a>, +<a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>, +<a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>, +<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>. diff --git a/osfmk/man/MO_default_server.html b/osfmk/man/MO_default_server.html index 8d9a552c5..7e3e707f8 100755 --- a/osfmk/man/MO_default_server.html +++ b/osfmk/man/MO_default_server.html @@ -1 +1,62 @@ -<h2>memory_object_default_server</h2> <hr> <p> <strong>Function</strong> - Handle kernel operation request targeted for the default pager. <h3>SYNOPSIS</h3> <pre> <strong>boolean_t memory_object_default_server</strong> <strong>(mach_msg_header_t</strong> <var>request_msg</var>, <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>in_msg</var> <dd> [pointer to in structure] The memory manager message received from the kernel. <p> <dt> <var>out_msg</var> <dd> [out structure] A reply message. Note that no kernel messages to a memory manager expect a direct reply. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_default_server</strong> function is the MIG generated server handling function to handle messages from the kernel targeted to the default memory manager. This server function only handles messages unique to the default memory manager. Messages that are common to all memory managers are handled by <strong>memory_object_server</strong>. <p> A \*Vmemory manager\*O is a server task that responds to specific messages from the kernel in order to handle memory management functions for the kernel. The <strong>memory_object_default_server</strong> function performs all necessary argument handling for a kernel message and calls one of the default memory manager functions. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>TRUE</strong> <dd> The message was handled and the appropriate function was called. <p> <dt> <strong>FALSE</strong> <dd> The message did not apply to this memory management interface and no other action was taken. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server<strong></a>, <a href="memory_object_server.html"><strong>memory_object_server<strong></a>, <a href="memory_object_create.html"><strong>memory_object_create<strong></a>, <a href="MO_data_initialize.html"><strong>memory_object_data_initialize<strong></a>, <a href="DP_object_create.html"><strong>default_pager_object_create<strong></a>, <a href="default_pager_info.html"><strong>default_pager_info<strong></a>. \ No newline at end of file +<h2>memory_object_default_server</h2> +<hr> +<p> +<strong>Function</strong> - Handle kernel operation request targeted for the default pager. +<h3>SYNOPSIS</h3> +<pre> +<strong>boolean_t memory_object_default_server</strong> + <strong>(mach_msg_header_t</strong> <var>request_msg</var>, + <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>in_msg</var> +<dd> +[pointer to in structure] +The memory manager message received from +the kernel. +<p> +<dt> <var>out_msg</var> +<dd> +[out structure] +A reply message. Note that no kernel messages to a +memory manager expect a direct reply. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_default_server</strong> function is the MIG generated server +handling function to handle messages from the kernel targeted to the default +memory manager. This server function only handles messages unique +to the default +memory manager. Messages that are common to all memory managers are +handled by <strong>memory_object_server</strong>. +<p> +A \*Vmemory manager\*O +is a server task that responds to specific messages from the +kernel in order to handle memory management functions for the kernel. The +<strong>memory_object_default_server</strong> function performs all necessary argument +handling for a kernel message and calls one of the default memory manager +functions. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The message was handled and the appropriate function was called. +<p> +<dt> <strong>FALSE</strong> +<dd> +The message did not apply to this memory management interface and +no other action was taken. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server<strong></a>, +<a href="memory_object_server.html"><strong>memory_object_server<strong></a>, +<a href="memory_object_create.html"><strong>memory_object_create<strong></a>, +<a href="MO_data_initialize.html"><strong>memory_object_data_initialize<strong></a>, +<a href="DP_object_create.html"><strong>default_pager_object_create<strong></a>, +<a href="default_pager_info.html"><strong>default_pager_info<strong></a>. + diff --git a/osfmk/man/MO_get_attributes.html b/osfmk/man/MO_get_attributes.html index 15d33f797..917a4898b 100755 --- a/osfmk/man/MO_get_attributes.html +++ b/osfmk/man/MO_get_attributes.html @@ -1 +1,73 @@ -<h2>memory_object_get_attributes</h2> <hr> <p> <strong>Function</strong> - Return current attributes for a memory object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_get_attributes</strong> <strong>(memory_object_control_t</strong> <var>memory_control</var>, <strong>memory_object_flavor_t</strong> <var>flavor</var>, <strong>memory_object_info_t</strong> <var>attributes</var>, <strong>mach_msg_type_number_t</strong> <var>attributes_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used by the memory manager for cache management requests. This port is provided by the kernel in a <strong>memory_object_notify</strong> call. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of information to be returned. Valid values are: <dl> <p> <dt> <strong>MEMORY_OBJECT_PERFORMANCE_INFO</strong> <dd> Performance related attributes such as the cache indicator and the cluster size. <var>attributes</var> should specify a structure of type <strong>memory_object_perf_info</strong>. <p> <dt> <strong>MEMORY_OBJECT_BEHAVIOR_INFO</strong> <dd> Behavior related attributes such as the copy strategy and sync invalidate flag. <var>attributes</var> should specify a structure of type <strong>memory_object_behavior_info</strong>. <dt> <strong>MEMORY_OBJECT_ATTRIBUTES_INFO</strong> <dd> Behavior and performance related attributes such as the copy strategy, cache indicator, and cluster size. <var>attributes</var> should specify a structure of type <strong>memory_object_attr_info</strong>. </dl> <p> <dt> <var>attributes</var> <dd> [out structure] Current attributes. <p> <dt> <var>attributes_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_get_attributes</strong> function retrieves the current attributes for the specified memory object. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>. <p> Data Structures: <a href="memory_object_perf_info.html"><strong>memory_object_perf_info</strong></a>, <a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>. \ No newline at end of file +<h2>memory_object_get_attributes</h2> +<hr> +<p> +<strong>Function</strong> - Return current attributes for a memory object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_get_attributes</strong> + <strong>(memory_object_control_t</strong> <var>memory_control</var>, + <strong>memory_object_flavor_t</strong> <var>flavor</var>, + <strong>memory_object_info_t</strong> <var>attributes</var>, + <strong>mach_msg_type_number_t</strong> <var>attributes_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used by the memory manager for cache management requests. +This port is provided by the kernel in a <strong>memory_object_notify</strong> call. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of information to be returned. Valid values are: +<dl> +<p> +<dt> <strong>MEMORY_OBJECT_PERFORMANCE_INFO</strong> +<dd> +Performance related attributes such as the cache indicator and +the cluster size. <var>attributes</var> should specify a structure of type +<strong>memory_object_perf_info</strong>. +<p> +<dt> <strong>MEMORY_OBJECT_BEHAVIOR_INFO</strong> +<dd> +Behavior related attributes such as the copy strategy and sync +invalidate flag. <var>attributes</var> should specify a structure of type +<strong>memory_object_behavior_info</strong>. + <dt> <strong>MEMORY_OBJECT_ATTRIBUTES_INFO</strong> +<dd> +Behavior and performance related attributes such as the copy strategy, +cache indicator, and cluster size. <var>attributes</var> should specify a structure of type +<strong>memory_object_attr_info</strong>. +</dl> +<p> +<dt> <var>attributes</var> +<dd> +[out structure] +Current attributes. +<p> +<dt> <var>attributes_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_get_attributes</strong> function retrieves +the current attributes for +the specified memory object. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>. +<p> +Data Structures: +<a href="memory_object_perf_info.html"><strong>memory_object_perf_info</strong></a>, +<a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>. diff --git a/osfmk/man/MO_lock_completed.html b/osfmk/man/MO_lock_completed.html index aa62805c2..ff1e19a0c 100755 --- a/osfmk/man/MO_lock_completed.html +++ b/osfmk/man/MO_lock_completed.html @@ -1 +1,95 @@ -<h2>memory_object_lock_completed</h2> <hr> <p> <strong>Server Interface</strong> - Report to memory manager that a previous consistency control request has been handled. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_lock_completed</strong> <strong>(memory_object_t</strong> <var>reply_port</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>length</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_lock_completed</strong> <strong>(memory_object_t</strong> <var>reply_port</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>length</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>reply_port</var> <dd> [in reply (receive) right] The port supplied in the corresponding <strong>memory_object_lock_request</strong> call. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the port named in the <strong>memory_object_lock_completed</strong> message. <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used for a response by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object. <p> <dt> <var>length</var> <dd> [in scalar] The number of bytes to which the call refers, starting at <var>offset</var>. The number converts to an integral number of memory object pages. </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_lock_completed</strong> function is called as the result of a kernel message confirming the kernel's action in response to a <strong>memory_object_lock_request</strong> call from the memory manager. The memory manager can use the <strong>memory_object_lock_request</strong> call to: <ul> <li> Alter access restrictions specified in the <strong>memory_object_data_supply</strong> call or a previous <strong>memory_object_lock_request</strong> call. <p> <li> Write back modifications made in memory. <p> <li> Invalidate its cached data. </ul> <p> When the kernel completes the requested actions, it calls <strong>memory_object_lock_completed</strong> (asynchronously) using the port explicitly provided in the <strong>memory_object_lock_request</strong> call. Because the memory manager cannot know which pages have been modified, or even which pages remain in the cache, it cannot know how many pages will be written back in response to a <strong>memory_object_lock_request</strong> call. Receiving the <strong>memory_object_lock_completed</strong> call is the only sure means of detecting completion. The completion call includes the offset and length values from the consistency request to distinguish it from other consistency requests. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>, <a href="memory_object_server.html"><strong>memory_object_server</strong></a>, <a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. \ No newline at end of file +<h2>memory_object_lock_completed</h2> +<hr> +<p> +<strong>Server Interface</strong> - Report to memory manager that a previous consistency control request has been handled. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_lock_completed</strong> + <strong>(memory_object_t</strong> <var>reply_port</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>length</var><strong>);</strong> + + +<strong>kern_return_t seqnos_memory_object_lock_completed</strong> + <strong>(memory_object_t</strong> <var>reply_port</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>length</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>reply_port</var> +<dd> +[in reply (receive) right] +The port supplied in the corresponding +<strong>memory_object_lock_request</strong> call. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the port +named in the <strong>memory_object_lock_completed</strong> message. +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used for a response by the memory manager. If the memory +object has been supplied to more than one kernel, this parameter +identifies the kernel that is making the call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object. +<p> +<dt> <var>length</var> +<dd> +[in scalar] +The number of bytes to which the call refers, starting at +<var>offset</var>. The number converts to an integral number of memory object +pages. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_lock_completed</strong> function is called as +the result of a kernel +message confirming the kernel's action in response to a +<strong>memory_object_lock_request</strong> call from the memory manager. +The memory manager can use the <strong>memory_object_lock_request</strong> call to: +<ul> +<li> +Alter access restrictions specified in the <strong>memory_object_data_supply</strong> +call or a previous <strong>memory_object_lock_request</strong> call. +<p> +<li> +Write back modifications made in memory. +<p> +<li> +Invalidate its cached data. +</ul> +<p> +When the kernel completes the requested actions, it calls +<strong>memory_object_lock_completed</strong> (asynchronously) using +the port explicitly provided in the +<strong>memory_object_lock_request</strong> call. Because the memory manager cannot +know which pages have been modified, or even which pages remain in the +cache, it cannot know how many pages will be written back in response to a +<strong>memory_object_lock_request</strong> call. Receiving the +<strong>memory_object_lock_completed</strong> call is the only sure +means of detecting completion. The completion call +includes the offset and length values from the consistency request +to distinguish +it from other consistency requests. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>, +<a href="memory_object_server.html"><strong>memory_object_server</strong></a>, +<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. diff --git a/osfmk/man/MO_supply_completed.html b/osfmk/man/MO_supply_completed.html index 087304456..54d4d0827 100755 --- a/osfmk/man/MO_supply_completed.html +++ b/osfmk/man/MO_supply_completed.html @@ -1 +1,104 @@ -<h2>memory_object_supply_completed</h2> <hr> <p> <strong>Server Interface</strong> - Return results associated with the kernel's handling of a particular memory manager request. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_supply_completed</strong> <strong>(memory_object_t</strong> <var>reply_port</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>length</var>, <strong>kern_return_t</strong> <var>result</var>, <strong>vm_offset_t</strong> <var>error_offset</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_supply_completed</strong> <strong>(memory_object_t</strong> <var>reply_port</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>length</var>, <strong>kern_return_t</strong> <var>result</var>, <strong>vm_offset_t</strong> <var>error_offset</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>reply_port</var> <dd> [in reply (receive) right] The port supplied in the corresponding <strong>memory_object_data_supply</strong> call. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the port named in the <strong>memory_object_data_supply</strong> call. <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used for a response by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object from the corresponding data supply call. <p> <dt> <var>length</var> <dd> [in scalar] The number of bytes accepted. The number converts to an integral number of memory object pages. <p> <dt> <var>result</var> <dd> [in scalar] A kernel return code indicating the result of the supply operation, possibly <strong>KERN_SUCCESS</strong>. <strong>KERN_MEMORY_PRESENT</strong> is currently the only error returned; other errors (invalid arguments, for example) abort the data supply operation. <p> <dt> <var>error_offset</var> <dd> [in scalar] The offset within the memory object where the first error occurred. </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_supply_completed</strong> function is called as the result of a kernel message confirming the kernel's action in response to a <strong>memory_object_data_supply</strong> call from the memory manager. <p> When the kernel accepts the pages, it calls <strong>memory_object_supply_completed</strong> (asynchronously) using the port explicitly provided in the <strong>memory_object_data_supply</strong> call. Because the data supply call can provide multiple pages, not all of which the kernel may necessarily accept and some of which the kernel may have to return to the manager (if precious), the kernel provides this response. If the kernel does not accept all of the pages in the data supply message, it will indicate so in the completion response. If the pages not accepted are precious, they will be returned (in <strong>memory_object_data_return</strong> messages) before it sends this completion message. The completion call includes the offset and length values from the supply request to distinguish it from other supply requests. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>, <a href="memory_object_server.html"><strong>memory_object_server</strong></a>, <a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. \ No newline at end of file +<h2>memory_object_supply_completed</h2> +<hr> +<p> +<strong>Server Interface</strong> - Return results associated with the kernel's handling of a particular memory manager request. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_supply_completed</strong> + <strong>(memory_object_t</strong> <var>reply_port</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>length</var>, + <strong>kern_return_t</strong> <var>result</var>, + <strong>vm_offset_t</strong> <var>error_offset</var><strong>);</strong> + + +<strong>kern_return_t seqnos_memory_object_supply_completed</strong> + <strong>(memory_object_t</strong> <var>reply_port</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>length</var>, + <strong>kern_return_t</strong> <var>result</var>, + <strong>vm_offset_t</strong> <var>error_offset</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>reply_port</var> +<dd> +[in reply (receive) right] +The port supplied in the corresponding +<strong>memory_object_data_supply</strong> call. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the port +named in the <strong>memory_object_data_supply</strong> call. +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used for a response by the memory manager. If the memory +object has been supplied to more than one kernel, this parameter +identifies the kernel that is making the call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object from the corresponding +data supply call. +<p> +<dt> <var>length</var> +<dd> +[in scalar] +The number of bytes accepted. The number converts to an +integral number of memory object pages. +<p> +<dt> <var>result</var> +<dd> +[in scalar] +A kernel return code indicating the result of the supply +operation, possibly <strong>KERN_SUCCESS</strong>. <strong>KERN_MEMORY_PRESENT</strong> is +currently the only error returned; other errors (invalid arguments, for +example) abort the data supply operation. +<p> +<dt> <var>error_offset</var> +<dd> +[in scalar] +The offset within the memory object where the first error +occurred. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_supply_completed</strong> function is called +as the result of a +kernel message confirming the kernel's action in response to a +<strong>memory_object_data_supply</strong> call from the memory manager. +<p> +When the kernel accepts the pages, it calls +<strong>memory_object_supply_completed</strong> +(asynchronously) using the port explicitly provided in the +<strong>memory_object_data_supply</strong> call. Because the data supply +call can provide multiple pages, not +all of which the kernel may necessarily accept and some of which the kernel +may have to return to the manager (if precious), the kernel provides this +response. If the kernel does not accept all of the pages in +the data supply message, +it will indicate so in the completion response. If the pages not accepted are +precious, they will be returned (in <strong>memory_object_data_return</strong> +messages) before +it sends this completion message. The completion call includes the offset and +length values from the supply request to distinguish it from other supply +requests. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>, +<a href="memory_object_server.html"><strong>memory_object_server</strong></a>, +<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. diff --git a/osfmk/man/MP_allocate_subsystem.html b/osfmk/man/MP_allocate_subsystem.html index 195094e9e..2961679eb 100755 --- a/osfmk/man/MP_allocate_subsystem.html +++ b/osfmk/man/MP_allocate_subsystem.html @@ -1 +1,74 @@ -<h2>mach_port_allocate_subsystem</h2> <hr> <p> <strong>Function</strong> - Create a port right associated with the caller-specified subsystem. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_allocate_subsystem</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>subsystem_t</strong> <var>subsys</var>, <strong>mach_port_name_t</strong> <var>mach_port_name_t</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task acquiring the port right. <p> <dt> <var>subsys</var> <dd> [in scalar] The port right naming the subsystem the newly created port is to be associated with. <p> <dt> <var>name</var> <dd> [out scalar] The task's name for the port right. This can be any name that wasn't in use. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_allocate_subsystem</strong> function creates a new right and associates it with the specifed subsystem (specified via the <var>subsys</var> parameter) previously registered via a call to the <strong>mach_subsystem_create</strong> interface. The new right's name is returned in the <var>name</var> parameter. The association of this port with the subsystem is immutable for the life of the port. <p> Any RPC targeted at the new port will cause the kernel glue-code to locate the server function address and argument signature in the associated subsystem. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The right is allocated. <p> <dt> <strong>KERN_INVALID_TASK</strong> <dd> The space is null. <p> <dt> <strong>KERN_INVALID_TASK</strong> <dd> The space is dead. <p> <dt> <strong>KERN_RESOURCE_SHORTAGE</strong> <dd> Couldn't allocate memory. <p> <dt> <strong>KERN_NO_SPACE</strong> <dd> No room in space for another right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_subsystem_create.html"><strong>mach_subsystem_create</strong></a>, <a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>. \ No newline at end of file +<h2>mach_port_allocate_subsystem</h2> +<hr> +<p> +<strong>Function</strong> - Create a port right associated with the caller-specified subsystem. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_allocate_subsystem</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>subsystem_t</strong> <var>subsys</var>, + <strong>mach_port_name_t</strong> <var>mach_port_name_t</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] The task acquiring the port right. +<p> +<dt> <var>subsys</var> +<dd> +[in scalar] The port right naming the subsystem the newly created port +is to be associated with. +<p> +<dt> <var>name</var> +<dd> +[out scalar] The task's name for the port right. This can be any name +that wasn't in use. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_allocate_subsystem</strong> function creates a new right +and associates it +with the specifed subsystem (specified via the <var>subsys</var> parameter) +previously registered via a call to the +<strong>mach_subsystem_create</strong> interface. +The new right's name is returned in the <var>name</var> parameter. The +association of this port with the subsystem is immutable for the +life of the port. +<p> +Any RPC targeted at the new port will cause the kernel glue-code +to locate the server function address and argument signature in the +associated subsystem. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port +name parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The right is allocated. +<p> +<dt> <strong>KERN_INVALID_TASK</strong> +<dd> +The space is null. +<p> +<dt> <strong>KERN_INVALID_TASK</strong> +<dd> +The space is dead. +<p> +<dt> <strong>KERN_RESOURCE_SHORTAGE</strong> +<dd> +Couldn't allocate memory. +<p> +<dt> <strong>KERN_NO_SPACE</strong> +<dd> +No room in space for another right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_subsystem_create.html"><strong>mach_subsystem_create</strong></a>, +<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>. diff --git a/osfmk/man/MP_request_notification.html b/osfmk/man/MP_request_notification.html index 1d41e4b74..34125f0ad 100755 --- a/osfmk/man/MP_request_notification.html +++ b/osfmk/man/MP_request_notification.html @@ -1 +1,147 @@ -<h2>mach_port_request_notification</h2> <hr> <p> <strong>Function</strong> - Request notification of the specified port event type. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_request_notification</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_msg_id_t</strong> <var>variant</var>, <strong>mach_port_mscount_t</strong> <var>sync</var>, <strong>mach_port_send_once_t</strong> <var>notify</var>, <strong>mach_msg_type_name_t</strong> <var>notify_type</var>, <strong>mach_port_send_once_t</strong> <var>*previous</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task holding the specified right. <p> <dt> <var>name</var> <dd> [in scalar] The task's name for the right. <p> <dt> <var>variant</var> <dd> [in scalar] The type of notification. <p> <dt> <var>sync</var> <dd> [in scalar] Some variants use this value to overcome race conditions. <p> <dt> <var>notify</var> <dd> [in notify send-once or receive (to be converted to send-once) right] A send-once right, to which the notification will be sent. <p> <dt> <var>notify_type</var> <dd> [in scalar] IPC type of the <var>notify</var> right; either <strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or <strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>. <p> <dt> <var>previous</var> <dd> [out notify send-once right] The previously registered send-once right. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_request_notification</strong> function registers a request for a notification and supplies a send-once right that the notification will use. It is an atomic swap, returning the previously registered send-once right (or <strong>MACH_PORT_NULL</strong> for none). A notification request may be cancelled by providing <strong>MACH_PORT_NULL</strong>. <p> The <var>variant</var> argument takes the following values: <dl> <dt> <strong>MACH_NOTIFY_PORT_DESTROYED</strong> <dd> <var>sync</var> must be zero. The <var>name</var> must specify a receive right, and the call requests a port-destroyed notification for the receive right. If the receive right were to have been destroyed, for instance by <strong>mach_port_destroy</strong>, then instead the receive right will be sent in a port-destroyed notification to the registered send-once right. <p> <dt> <strong>MACH_NOTIFY_DEAD_NAME</strong> <dd> The call requests a dead-name notification. <var>name</var> specifies send, receive, or send-once rights for a port. If the port is destroyed (and the right remains, becoming a dead name), then a dead-name notification which carries the name of the right will be sent to the registered send-once right. If <var>sync</var> is non-zero, the <var>name</var> may specify a dead name, and a dead-name notification is immediately generated. <p> Whenever a dead-name notification is generated, the user reference count of the dead name is incremented. For example, a send right with two user refs has a registered dead-name request. If the port is destroyed, the send right turns into a dead name with three user refs (instead of two), and a dead-name notification is generated. <p> If the name is made available for reuse, perhaps because of <strong>mach_port_destroy</strong> or <strong>mach_port_mod_refs</strong>, or the name denotes a send-once right which has a message sent to it, then the registered send-once right is used to generate a port-deleted notification instead. <p> <dt> <strong>MACH_NOTIFY_NO_SENDERS</strong> <dd> The call requests a no-senders notification. <var>name</var> must specify a receive right. If the receive right's make-send count is greater than or equal to the sync value, and it has no extant send rights, than an immediate no-senders notification is generated. Otherwise the notification is generated when the receive right next loses its last extant send right. In either case, any previously registered send-once right is returned. <p> The no-senders notification carries the value the port's make-send count had when it was generated. The make-send count is incremented whenever a send right is made directly from a receive right. The make-send count is reset to zero when the receive right is carried in a message. <p> When moving a receive right, no-senders notifications are canceled, with a send-once notification sent to indicate the cancelation. </dl> <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> <var>name</var> did not denote a right. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> <var>name</var> denoted an invalid right. <p> <dt> <strong>KERN_INVALID_CAPABILITY</strong> <dd> <var>notify</var> was invalid. </dl> <p> When using <strong>MACH_NOTIFY_DEAD_NAME</strong>: <dl> <p> <dt> <strong>KERN_UREFS_OVERFLOW</strong> <dd> <var>name</var> denotes a dead name, but generating an immediate dead-name notification would overflow the name's user-reference count. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>. \ No newline at end of file +<h2>mach_port_request_notification</h2> +<hr> +<p> +<strong>Function</strong> - Request notification of the specified port event type. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_request_notification</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_msg_id_t</strong> <var>variant</var>, + <strong>mach_port_mscount_t</strong> <var>sync</var>, + <strong>mach_port_send_once_t</strong> <var>notify</var>, + <strong>mach_msg_type_name_t</strong> <var>notify_type</var>, + <strong>mach_port_send_once_t</strong> <var>*previous</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task holding the specified right. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The task's name for the right. +<p> +<dt> <var>variant</var> +<dd> +[in scalar] +The type of notification. +<p> +<dt> <var>sync</var> +<dd> +[in scalar] +Some variants use this value to overcome race conditions. +<p> +<dt> <var>notify</var> +<dd> +[in notify send-once or receive (to be converted to send-once) right] +A +send-once right, to which the notification will be sent. +<p> +<dt> <var>notify_type</var> +<dd> +[in scalar] +IPC type of the <var>notify</var> right; either +<strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or <strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>. +<p> +<dt> <var>previous</var> +<dd> +[out notify send-once right] +The previously registered send-once right. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_request_notification</strong> function registers a request for a +notification and supplies a send-once right that the notification +will use. It is an atomic +swap, returning the previously registered send-once right (or +<strong>MACH_PORT_NULL</strong> for none). A notification request may be +cancelled by providing <strong>MACH_PORT_NULL</strong>. +<p> +The <var>variant</var> argument takes the following values: +<dl> +<dt> <strong>MACH_NOTIFY_PORT_DESTROYED</strong> +<dd> +<var>sync</var> must be zero. The <var>name</var> must specify a receive right, +and the call requests a port-destroyed notification for the receive +right. If the receive right were to have been destroyed, for instance +by <strong>mach_port_destroy</strong>, then instead the receive right will be +sent in a port-destroyed notification to the registered send-once right. +<p> +<dt> <strong>MACH_NOTIFY_DEAD_NAME</strong> +<dd> +The call requests a dead-name notification. <var>name</var> specifies send, +receive, or send-once rights for a port. If the port is destroyed (and the +right remains, becoming a dead name), then a dead-name notification +which carries the name of the right will be sent to the registered +send-once right. If <var>sync</var> is non-zero, +the <var>name</var> may specify a dead name, and +a dead-name notification is immediately generated. +<p> +Whenever a dead-name notification is generated, the user reference +count of the dead name is incremented. For example, a send right with +two user refs has a registered dead-name request. If the port is +destroyed, the send right turns into a dead name with three user refs +(instead of two), and a dead-name notification is generated. +<p> +If the name is made available for reuse, perhaps because of +<strong>mach_port_destroy</strong> or <strong>mach_port_mod_refs</strong>, +or the name denotes a +send-once right which has a message sent to it, then the registered send-once +right is used to generate a port-deleted notification instead. +<p> +<dt> <strong>MACH_NOTIFY_NO_SENDERS</strong> +<dd> +The call requests a no-senders notification. <var>name</var> must specify a +receive right. If the receive right's make-send count is greater than or +equal to the sync value, and it has no extant send rights, than an +immediate no-senders notification is generated. Otherwise the notification is +generated when the receive right next loses its last extant send right. In +either case, any previously registered send-once right is returned. +<p> +The no-senders notification carries the value the port's make-send +count had when it was generated. The make-send count is incremented +whenever a send right is made directly from a receive right. The +make-send count is reset to zero when the receive right is carried in a +message. +<p> +When moving a receive right, no-senders notifications are canceled, +with a send-once notification sent to indicate the cancelation. +</dl> +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +<var>name</var> did not denote a right. +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +<var>name</var> denoted an invalid right. +<p> +<dt> <strong>KERN_INVALID_CAPABILITY</strong> +<dd> +<var>notify</var> was invalid. +</dl> +<p> +When using <strong>MACH_NOTIFY_DEAD_NAME</strong>: +<dl> +<p> +<dt> <strong>KERN_UREFS_OVERFLOW</strong> +<dd> +<var>name</var> denotes a dead name, but generating an immediate dead-name +notification would overflow the name's user-reference count. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_msg.html"><strong>mach_msg</strong></a>, +<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>. diff --git a/osfmk/man/P_set_policy_control.html b/osfmk/man/P_set_policy_control.html index 763cf3b88..7f37f6ed7 100755 --- a/osfmk/man/P_set_policy_control.html +++ b/osfmk/man/P_set_policy_control.html @@ -1 +1,91 @@ -<h2>processor_set_policy_control</h2> <hr> <p> <strong>Function</strong> - Set target processor set's scheduling policy state. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_set_policy_control</strong> <strong>(processor_set_t</strong> <var>processor_set_control</var>, <strong>processor_set_flavor_t</strong> <var>flavor</var>, <strong>processor_set_info_t</strong> <var>policy_info</var>, <strong>mach_msg_type_number_t*</strong> <var>policy_info_count</var>, <strong>boolean_t</strong> <var>change_tasks_threads</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor_set_control</var> <dd> [in processor-set-control send right] A processor set control port. <dt> <var>flavor</var> <dd> [in scalar] The type of policy change to make. <dl> <dt> <strong>PROCESSOR_SET_TIMESHARE_DEFAULT</strong> <dd> Change the base attributes for the timeshare scheduling policy, making timeshare the default policy. The structure is <strong>policy_timeshare_base</strong>. <dt> <strong>PROCESSOR_SET_FIFO_DEFAULT</strong> <dd> Change the base attributes for the FIFO (first-in, first-out) scheduling policy, making FIFO the default policy. The structure is <strong>policy_fifo_base</strong>. <dt> <strong>PROCESSOR_SET_RR_DEFAULT</strong> <dd> Changed the base attributes for the round-robin scheduling policy, making round robin the default policy. The structure is <strong>policy_rr_base</strong>. <dt> <strong>PROCESSOR_SET_TIMESHARE_LIMITS</strong> <dd> Change the limits on the allowed timeshare policy attributes. The structure is defined by <strong>policy_timeshare_limit</strong>. <dt> <strong>PROCESSOR_SET_RR_LIMITS</strong> <dd> Change the limits on the allowed round robin policy attributes. The structure is defined by <strong>policy_rr_limit</strong>. <dt> <strong>PROCESSOR_SET_FIFO_LIMITS</strong> <dd> Change the limits on the allowed first-in, first-out policy attributes. The structure is defined by <strong>policy_fifo_limit</strong>. <dt> <strong>PROCESSOR_SET_ENABLED_POLICIES</strong> <dd> Change the set of enabled policies. The data is a bit-vector. </dl> <dt> <var>policy_info</var> <dd> [in structure] The relevant policy information. <dt> <var>policy_info_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). <dt> <var>change_tasks_threads</var> <dd> [in scalar] If true, any assigned task or thread whose policy is no longer enabled or whose scheduling attributes exceed the current limits will have their limits adjusted or their policy set to the default as appropriate. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_policy_control</strong> function controls scheduling attributes governing the processor set. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_statistics.html">processor_set_statistics</a>, <a href="processor_set_create.html">processor_set_create</a>, <a href="processor_set_default.html">processor_set_default</a>, <a href="processor_assign.html">processor_assign</a>, <a href="processor_set_info.html">processor_set_info</a>. <p> Data Structures: <a href="policy_timeshare_info.html">policy_timeshare_info</a>, <a href="policy_rr_info.html">policy_rr_info</a>, <a href="policy_fifo_info.html">policy_fifo_info</a>. \ No newline at end of file +<h2>processor_set_policy_control</h2> +<hr> +<p> +<strong>Function</strong> - Set target processor set's scheduling policy state. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_set_policy_control</strong> + <strong>(processor_set_t</strong> <var>processor_set_control</var>, + <strong>processor_set_flavor_t</strong> <var>flavor</var>, + <strong>processor_set_info_t</strong> <var>policy_info</var>, + <strong>mach_msg_type_number_t*</strong> <var>policy_info_count</var>, + <strong>boolean_t</strong> <var>change_tasks_threads</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor_set_control</var> +<dd> +[in processor-set-control send right] +A processor set control port. +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of policy change to make. +<dl> +<dt> <strong>PROCESSOR_SET_TIMESHARE_DEFAULT</strong> +<dd> +Change the base attributes for the timeshare scheduling +policy, making timeshare the default policy. The structure is +<strong>policy_timeshare_base</strong>. +<dt> <strong>PROCESSOR_SET_FIFO_DEFAULT</strong> +<dd> +Change the base attributes for the FIFO (first-in, first-out) +scheduling policy, making FIFO the default policy. The +structure is <strong>policy_fifo_base</strong>. +<dt> <strong>PROCESSOR_SET_RR_DEFAULT</strong> +<dd> +Changed the base attributes for the round-robin scheduling +policy, making round robin the default policy. The structure is +<strong>policy_rr_base</strong>. +<dt> <strong>PROCESSOR_SET_TIMESHARE_LIMITS</strong> +<dd> +Change the limits on the allowed timeshare policy attributes. +The structure is defined by <strong>policy_timeshare_limit</strong>. +<dt> <strong>PROCESSOR_SET_RR_LIMITS</strong> +<dd> +Change the limits on the allowed round robin policy +attributes. The structure is defined by <strong>policy_rr_limit</strong>. +<dt> <strong>PROCESSOR_SET_FIFO_LIMITS</strong> +<dd> +Change the limits on the allowed first-in, first-out policy +attributes. The structure is defined by <strong>policy_fifo_limit</strong>. +<dt> <strong>PROCESSOR_SET_ENABLED_POLICIES</strong> +<dd> +Change the set of enabled policies. The data is a bit-vector. +</dl> +<dt> <var>policy_info</var> +<dd> +[in structure] +The relevant policy information. +<dt> <var>policy_info_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +<dt> <var>change_tasks_threads</var> +<dd> +[in scalar] +If true, any assigned task or thread whose policy is no +longer enabled or whose scheduling attributes exceed the current limits will +have their limits adjusted or their policy set to the default as +appropriate. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_policy_control</strong> function controls +scheduling attributes governing the processor set. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_statistics.html">processor_set_statistics</a>, +<a href="processor_set_create.html">processor_set_create</a>, +<a href="processor_set_default.html">processor_set_default</a>, +<a href="processor_assign.html">processor_assign</a>, +<a href="processor_set_info.html">processor_set_info</a>. +<p> +Data Structures: +<a href="policy_timeshare_info.html">policy_timeshare_info</a>, +<a href="policy_rr_info.html">policy_rr_info</a>, +<a href="policy_fifo_info.html">policy_fifo_info</a>. diff --git a/osfmk/man/P_set_policy_disable.html b/osfmk/man/P_set_policy_disable.html index 5c391db21..80aec0ead 100755 --- a/osfmk/man/P_set_policy_disable.html +++ b/osfmk/man/P_set_policy_disable.html @@ -1 +1,50 @@ -<h2>processor_set_policy_disable</h2> <hr> <p> <strong>Function</strong> - Disables a scheduling policy for a processor set. <h3>SYNOPSIS</h3> <pre> <strong>#include< mach/mach_host.h></strong> <strong>kern_return_t processor_set_policy_disable</strong> <strong>(processor_set_t</strong> <var>processor_set</var>, <strong>int</strong> <var>policy</var>, <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor_set</var> <dd> [in processor-set-control port] The control port for the processor set for which a scheduling policy is to be disabled. <dt> <var>policy</var> <dd> [in scalar] Policy to be disabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI. <dt> <var>change_threads</var> <dd> [in scalar] If true, causes the scheduling policy for all threads currently running with policy to POLICY_TIMESHARE. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_policy_disable</strong> function restricts the set of scheduling policies allowed for <var>processor_set</var>. The set of scheduling policies allowed for a processor set is the set of policies allowed to be set for threads assigned to that processor set. The current set of permitted policies can be obtained from <strong>processor_set_info</strong>. Timesharing may not be forbidden for any processor set. This is a compromise to reduce the complexity of the assign operation; any thread whose <var>policy</var> is forbidden by its target processor set has its <var>policy</var> reset to timesharing. Disabling a scheduling <var>policy</var> for a processor set has no effect on threads currently assigned to that processor set unless <var>change_threads</var> is TRUE, in which case their policies will be reset to timesharing. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="P_set_policy_enable.html">processor_set_policy_enable</a>, <a href="processor_set_info.html">processor_set_info</a>, <a href="thread_policy.html">thread_policy</a>. \ No newline at end of file +<h2>processor_set_policy_disable</h2> +<hr> +<p> +<strong>Function</strong> - Disables a scheduling policy for a processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< mach/mach_host.h></strong> + +<strong>kern_return_t processor_set_policy_disable</strong> + <strong>(processor_set_t</strong> <var>processor_set</var>, + <strong>int</strong> <var>policy</var>, + <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor_set</var> +<dd> +[in processor-set-control port] The control port for the processor set for which a scheduling policy is to be disabled. +<dt> <var>policy</var> +<dd> +[in scalar] Policy to be disabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI. +<dt> <var>change_threads</var> +<dd> +[in scalar] If true, causes the scheduling policy for all threads currently running with policy to POLICY_TIMESHARE. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_policy_disable</strong> +function restricts the set of scheduling policies allowed for +<var>processor_set</var>. The set of scheduling policies allowed for a +processor set is the set of policies allowed to be set for threads +assigned to that processor set. The current set of permitted policies +can be obtained from <strong>processor_set_info</strong>. Timesharing may +not be forbidden for any processor set. This is a compromise to reduce +the complexity of the assign operation; any thread whose +<var>policy</var> is forbidden by its target processor set has its +<var>policy</var> reset to timesharing. Disabling a scheduling +<var>policy</var> for a processor set has no effect on threads +currently assigned to that processor set unless +<var>change_threads</var> is TRUE, in which case their policies will +be reset to timesharing. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="P_set_policy_enable.html">processor_set_policy_enable</a>, +<a href="processor_set_info.html">processor_set_info</a>, +<a href="thread_policy.html">thread_policy</a>. diff --git a/osfmk/man/P_set_policy_enable.html b/osfmk/man/P_set_policy_enable.html index 8bb760d6a..966c80d95 100755 --- a/osfmk/man/P_set_policy_enable.html +++ b/osfmk/man/P_set_policy_enable.html @@ -1 +1,38 @@ -<h2>processor_set_policy_enable</h2> <hr> <p> <strong>Function</strong> - Enables a scheduling policy for a processor set. <h3>SYNOPSIS</h3> <pre> <strong>#include< mach/mach_host.h></strong> <strong>kern_return_t processor_set_policy_enable</strong> <strong>(processor_set_t</strong> <var>processor_set</var>, <strong>int</strong> <var>policy</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor_set</var> <dd> [in processor-set-control port] The control port for the processor set for which a scheduling policy is to be enabled. <dt> <var>policy</var> <dd> [in scalar] Policy to be enabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_policy_enable</strong> function extends the set of scheduling policies allowed for <var>processor_set</var>. The set of scheduling policies allowed for a processor set is the set of policies allowed to be set for threads assigned to that processor set. The current set of permitted policies can be obtained from <strong>processor_set_info</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_info.html">processor_set_info</a>, <a href="P_set_policy_disable.html">processor_set_policy_disable</a>, <a href="thread_policy.html">thread_policy</a>. \ No newline at end of file +<h2>processor_set_policy_enable</h2> +<hr> +<p> +<strong>Function</strong> - Enables a scheduling policy for a processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< mach/mach_host.h></strong> + +<strong>kern_return_t processor_set_policy_enable</strong> + <strong>(processor_set_t</strong> <var>processor_set</var>, + <strong>int</strong> <var>policy</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor_set</var> +<dd> +[in processor-set-control port] The control port for the processor set for which a scheduling policy is to be enabled. +<dt> <var>policy</var> +<dd> +[in scalar] Policy to be enabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_policy_enable</strong> +function extends the set of scheduling policies allowed for +<var>processor_set</var>. The set of scheduling policies allowed for a +processor set is the set of policies allowed to be set for threads +assigned to that processor set. The current set of permitted policies +can be obtained from <strong>processor_set_info</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_info.html">processor_set_info</a>, +<a href="P_set_policy_disable.html">processor_set_policy_disable</a>, +<a href="thread_policy.html">thread_policy</a>. diff --git a/osfmk/man/SMO_default_server.html b/osfmk/man/SMO_default_server.html index d3da6bbd7..2f8043d98 100755 --- a/osfmk/man/SMO_default_server.html +++ b/osfmk/man/SMO_default_server.html @@ -1 +1,67 @@ -<h2>seqnos_memory_object_default_server</h2> <hr> <p> <strong>Function</strong> - Handle kernel operation request targeted for the default pager. <h3>SYNOPSIS</h3> <pre> <strong>boolean_t seqnos_memory_object_default_server</strong> <strong>(mach_msg_header_t</strong> <var>request_msg</var>, <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>in_msg</var> <dd> [pointer to in structure] The memory manager message received from the kernel. <p> <dt> <var>out_msg</var> <dd> [out structure] A reply message. Note that no kernel messages to a memory manager expect a direct reply. </dl> <h3>DESCRIPTION</h3> <p> The <strong>seqnos_memory_object_default_server</strong> function is the MIG generated server handling function to handle messages from the kernel targeted to the default memory manager. This server function only handles messages unique to the default memory manager. Messages that are common to all memory managers are handled by <strong>seqnos_memory_object_server</strong>. <p> A \*Vmemory manager\*O is a server task that responds to specific messages from the kernel in order to handle memory management functions for the kernel. The <strong>seqnos_memory_object_default_server</strong> function performs all necessary argument handling for a kernel message and calls one of the default memory manager functions. <h3>NOTES</h3> <p> <strong>seqnos_memory_object_default_server</strong> differs from <strong>memory_object_default_server</strong> in that it supplies message sequence numbers to the server interfaces it calls. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>TRUE</strong> <dd> The message was handled and the appropriate function was called. <p> <dt> <strong>FALSE</strong> <dd> The message did not apply to this memory management interface and no other action was taken. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="MO_default_server.html"><strong>memory_object_default_server<strong></a>, <a href="SMO_server.html"><strong>seqnos_memory_object_server<strong></a>, <a href="memory_object_create.html"><strong>seqnos_memory_object_create<strong></a>, <a href="MO_data_initialize.html"><strong>seqnos_memory_object_data_initialize<strong></a>, <a href="DP_object_create.html"><strong>seqnos_default_pager_object_create<strong></a>, <a href="default_pager_info.html"><strong>seqnos_default_pager_info<strong></a>. \ No newline at end of file +<h2>seqnos_memory_object_default_server</h2> +<hr> +<p> +<strong>Function</strong> - Handle kernel operation request targeted for the default pager. +<h3>SYNOPSIS</h3> +<pre> +<strong>boolean_t seqnos_memory_object_default_server</strong> + <strong>(mach_msg_header_t</strong> <var>request_msg</var>, + <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>in_msg</var> +<dd> +[pointer to in structure] +The memory manager message received from +the kernel. +<p> +<dt> <var>out_msg</var> +<dd> +[out structure] +A reply message. Note that no kernel messages to a +memory manager expect a direct reply. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>seqnos_memory_object_default_server</strong> function is +the MIG generated +server handling function to handle messages from the kernel targeted to the +default memory manager. This server function only handles messages unique to +the default memory manager. Messages that are common to all memory +managers are handled by <strong>seqnos_memory_object_server</strong>. +<p> +A \*Vmemory manager\*O +is a server task that responds to specific messages from the +kernel in order to handle memory management functions for the kernel. The +<strong>seqnos_memory_object_default_server</strong> function performs all necessary +argument handling for a kernel message and calls one of the default memory +manager functions. +<h3>NOTES</h3> +<p> +<strong>seqnos_memory_object_default_server</strong> differs from +<strong>memory_object_default_server</strong> in that it supplies message +sequence numbers to the server +interfaces it calls. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The message was handled and the appropriate function was called. +<p> +<dt> <strong>FALSE</strong> +<dd> +The message did not apply to this memory management interface and +no other action was taken. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="MO_default_server.html"><strong>memory_object_default_server<strong></a>, +<a href="SMO_server.html"><strong>seqnos_memory_object_server<strong></a>, +<a href="memory_object_create.html"><strong>seqnos_memory_object_create<strong></a>, +<a href="MO_data_initialize.html"><strong>seqnos_memory_object_data_initialize<strong></a>, +<a href="DP_object_create.html"><strong>seqnos_default_pager_object_create<strong></a>, +<a href="default_pager_info.html"><strong>seqnos_default_pager_info<strong></a>. diff --git a/osfmk/man/SMO_server.html b/osfmk/man/SMO_server.html index 6f3aaf971..7ed3730ca 100755 --- a/osfmk/man/SMO_server.html +++ b/osfmk/man/SMO_server.html @@ -1 +1,67 @@ -<h2>seqnos_memory_object_server</h2> <hr> <p> <strong>Function</strong> - Handle kernel operation request aimed at a given memory manager. <h3>SYNOPSIS</h3> <pre> <strong>boolean_t seqnos_memory_object_server</strong> <strong>(mach_msg_header_t</strong> <var>request_msg</var>, <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>in_msg</var> <dd> [pointer to in structure] The memory manager message received from the kernel. <p> <dt> <var>out_msg</var> <dd> [out structure] A reply message. No messages to a memory manager expect a direct reply, so this field is not used. </dl> <h3>DESCRIPTION</h3> <p> The <strong>seqnos_memory_object_server</strong> function is the MIG generated server handling function to handle messages from the kernel targeted to a memory manager. <p> A \*Vmemory manager\*O is a server task that responds to specific messages from the kernel in order to handle memory management functions for the kernel. The <strong>seqnos_memory_object_server</strong> function performs all necessary argument handling for a kernel message and calls one of the memory manager functions to interpret the message. <h3>NOTES</h3> <p> <strong>seqnos_memory_object_server</strong> differs from <strong>memory_object_server</strong> in that it supplies message sequence numbers to the server interfaces. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>TRUE</strong> <dd> The message was handled and the appropriate function was called. <p> <dt> <strong>FALSE</strong> <dd> The message did not apply to this memory management interface and no other action was taken. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server<strong></a>, <a href="memory_object_data_request.html"><strong>seqnos_memory_object_data_request<strong></a>, <a href="memory_object_data_unlock.html"><strong>seqnos_memory_object_data_unlock<strong></a>, <a href="memory_object_data_return.html"><strong>seqnos_memory_object_data_return<strong></a>, <a href="MO_supply_completed.html"><strong>seqnos_memory_object_supply_completed<strong></a>, <a href="MO_lock_completed.html"><strong>seqnos_memory_object_lock_completed<strong></a>, <a href="MO_change_completed.html"><strong>seqnos_seqnos_memory_object_change_completed<strong></a>, <a href="memory_object_terminate.html"><strong>seqnos_memory_object_terminate<strong></a>, <a href="memory_object_synchronize.html"><strong>seqnos_memory_object_synchronize<strong></a>, <a href="memory_object_server.html"><strong>memory_object_server<strong></a>. \ No newline at end of file +<h2>seqnos_memory_object_server</h2> +<hr> +<p> +<strong>Function</strong> - Handle kernel operation request aimed at a given memory manager. +<h3>SYNOPSIS</h3> +<pre> +<strong>boolean_t seqnos_memory_object_server</strong> + <strong>(mach_msg_header_t</strong> <var>request_msg</var>, + <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>in_msg</var> +<dd> +[pointer to in structure] +The memory manager message received from +the kernel. +<p> +<dt> <var>out_msg</var> +<dd> +[out structure] +A reply message. No messages to a memory manager +expect a direct reply, so this field is not used. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>seqnos_memory_object_server</strong> function is the MIG generated server +handling function to handle messages from the kernel targeted to a memory +manager. +<p> +A \*Vmemory manager\*O +is a server task that responds to specific messages from the +kernel in order to handle memory management functions for the kernel. The +<strong>seqnos_memory_object_server</strong> function performs all necessary argument +handling for a kernel message and calls one of the memory manager functions to +interpret the message. +<h3>NOTES</h3> +<p> +<strong>seqnos_memory_object_server</strong> differs from <strong>memory_object_server</strong> +in that it +supplies message sequence numbers to the server interfaces. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The message was handled and the appropriate function was called. +<p> +<dt> <strong>FALSE</strong> +<dd> +The message did not apply to this memory management interface and +no other action was taken. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server<strong></a>, +<a href="memory_object_data_request.html"><strong>seqnos_memory_object_data_request<strong></a>, +<a href="memory_object_data_unlock.html"><strong>seqnos_memory_object_data_unlock<strong></a>, +<a href="memory_object_data_return.html"><strong>seqnos_memory_object_data_return<strong></a>, +<a href="MO_supply_completed.html"><strong>seqnos_memory_object_supply_completed<strong></a>, +<a href="MO_lock_completed.html"><strong>seqnos_memory_object_lock_completed<strong></a>, +<a href="MO_change_completed.html"><strong>seqnos_seqnos_memory_object_change_completed<strong></a>, +<a href="memory_object_terminate.html"><strong>seqnos_memory_object_terminate<strong></a>, +<a href="memory_object_synchronize.html"><strong>seqnos_memory_object_synchronize<strong></a>, +<a href="memory_object_server.html"><strong>memory_object_server<strong></a>. diff --git a/osfmk/man/TS_exception_ports.html b/osfmk/man/TS_exception_ports.html index b6b26f7cc..df632bfcc 100755 --- a/osfmk/man/TS_exception_ports.html +++ b/osfmk/man/TS_exception_ports.html @@ -1 +1,185 @@ -<h2>thread_swap_exception_ports</h2> <hr> <p> <strong>Function</strong> - Swap exception ports for a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_swap_exception_ports</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>exception_mask_t</strong> <var>exception_types</var>, <strong>mach_port_t</strong> <var>exception_port</var>, <strong>exception_behavior_t</strong> <var>behavior</var>, <strong>thread_state_flavor_t</strong> <var>flavor</var>, <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>, <strong>old_exception_masks</strong> <var>old_exception_count</var>, <strong>exception_port_array_t</strong> <var>old_exception_ports</var>, <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>, <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] The thread for which to set the ports. <p> <dt> <var>exception_types</var> <dd> [in scalar] A flag word indicating the types of exceptions for which the exception port applies: <dl> <p> <dt> <strong>EXC_MASK_BAD_ACCESS</strong> <dd> Could not access memory. <p> <dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> <dd> Instruction failed. Illegal or undefined instruction or operand. <p> <dt> <strong>EXC_MASK_ARITHMETIC</strong> <dd> Arithmetic exception <p> <dt> <strong>EXC_MASK_EMULATION</strong> <dd> Emulation instruction. Emulation support instruction encountered. <p> <dt> <strong>EXC_MASK_SOFTWARE</strong> <dd> Software generated exception. <p> <dt> <strong>EXC_MASK_BREAKPOINT</strong> <dd> Trace, breakpoint, etc. <p> <dt> <strong>EXC_MASK_SYSCALL</strong> <dd> System call requested. <p> <dt> <strong>EXC_MASK_MACH_SYSCALL</strong> <dd> System call with a number in the Mach call range requested. </dl> <p> <dt> <var>exception_port</var> <dd> [in exception send right] The exception port for all selected exception types. <p> <dt> <var>behavior</var> <dd> [in scalar] Control of the behavior of the exception processing. Defined types are: <dl> <p> <dt> <strong>EXCEPTION_DEFAULT</strong> <dd> Send a <strong>catch_exception_raise</strong> message including the thread identity. <p> <dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong> <dd> Send a <strong>catch_exception_raise</strong> message including the thread identity. Mark the exception port (and associated exceptions) as protected. <p> <dt> <strong>EXCEPTION_STATE</strong> <dd> Send a <strong>catch_exception_raise_state</strong> message including the thread state. <p> <dt> <strong>EXCEPTION_STATE_PROTECTED</strong> <dd> Send a <strong>catch_exception_raise_state</strong> message including the thread state. Mark the exception port (and associated exceptions) as protected. <p> <dt> <strong>EXCEPTION_STATE_IDENTITY</strong> <dd> Send a <strong>catch_exception_raise_state_identity</strong> message including the thread identity and state. <p> <dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong> <dd> Send a <strong>catch_exception_raise_state_identity</strong> message including the thread identity and state. Mark the exception port (and associated exceptions) as protected. </dl> <p> <dt> <var>flavor</var> <dd> [in scalar] The type of state to be sent with the exception message. These types are defined in \*L<mach/thread_states.h>\*O. <p> <dt> <var>old_exception_masks</var> <dd> [out array of <var>exception_mask_t</var>] An array, each element being a mask specifying for which exception types the corresponding element of the other arrays apply. <p> <dt> <var>old_exception_count</var> <dd> [pointer to in/out scalar] On input, the maximum size of the array buffers; on output, the number of returned <exception type mask, exception port, behavior, flavor> sets returned. <p> <dt> <var>old_exception_ports</var> <dd> [out array of exception send rights] The returned exception ports. <p> <dt> <var>old_behaviors</var> <dd> [out array of <var>exception_behavior_t</var>] The type of exception message to be sent as with <var>behavior</var>. <p> <dt> <var>old_flavors</var> <dd> [out array of <var>thread_state_flavor_t</var>] The type of state to be sent with the exception message. These types are defined in \*L<mach/thread_states.h>\*O. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_swap_exception_ports</strong> function sets a specified set of exception ports belonging to <var>thread</var>, returning the old set. <h3>NOTES</h3> <p> If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is the host name port, Mach kernel traps are executed by the kernel as expected; any other value causes the attempted execution of these system call numbers to be considered an exception. <p> A "protected" exception port is one which cannot be fetched and for which exception processing cannot be aborted (<strong>thread_abort</strong>). <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_EXCEPTION_PROTECTED</strong> <dd> One of the requested exception ports is protected and cannot be returned. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>, <a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, <a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, <a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>, <a href="thread_abort.html"><strong>thread_abort</strong></a>. \ No newline at end of file +<h2>thread_swap_exception_ports</h2> +<hr> +<p> +<strong>Function</strong> - Swap exception ports for a thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_swap_exception_ports</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>exception_mask_t</strong> <var>exception_types</var>, + <strong>mach_port_t</strong> <var>exception_port</var>, + <strong>exception_behavior_t</strong> <var>behavior</var>, + <strong>thread_state_flavor_t</strong> <var>flavor</var>, + <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>, + <strong>old_exception_masks</strong> <var>old_exception_count</var>, + <strong>exception_port_array_t</strong> <var>old_exception_ports</var>, + <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>, + <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread for which to set the ports. +<p> +<dt> <var>exception_types</var> +<dd> +[in scalar] +A flag word indicating the types of exceptions for which the +exception port applies: +<dl> +<p> +<dt> <strong>EXC_MASK_BAD_ACCESS</strong> +<dd> +Could not access memory. +<p> +<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> +<dd> +Instruction failed. Illegal or undefined instruction or operand. +<p> +<dt> <strong>EXC_MASK_ARITHMETIC</strong> +<dd> +Arithmetic exception +<p> +<dt> <strong>EXC_MASK_EMULATION</strong> +<dd> +Emulation instruction. Emulation support instruction +encountered. +<p> +<dt> <strong>EXC_MASK_SOFTWARE</strong> +<dd> +Software generated exception. +<p> +<dt> <strong>EXC_MASK_BREAKPOINT</strong> +<dd> +Trace, breakpoint, etc. +<p> +<dt> <strong>EXC_MASK_SYSCALL</strong> +<dd> +System call requested. +<p> +<dt> <strong>EXC_MASK_MACH_SYSCALL</strong> +<dd> +System call with a number in the Mach call range requested. +</dl> +<p> +<dt> <var>exception_port</var> +<dd> +[in exception send right] +The exception port for all selected exception +types. +<p> +<dt> <var>behavior</var> +<dd> +[in scalar] +Control of the behavior of the exception processing. Defined +types are: +<dl> +<p> +<dt> <strong>EXCEPTION_DEFAULT</strong> +<dd> +Send a <strong>catch_exception_raise</strong> message including the thread +identity. +<p> +<dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong> +<dd> +Send a <strong>catch_exception_raise</strong> message including the thread +identity. Mark the exception port (and associated exceptions) +as protected. +<p> +<dt> <strong>EXCEPTION_STATE</strong> +<dd> +Send a <strong>catch_exception_raise_state</strong> message including the +thread state. +<p> +<dt> <strong>EXCEPTION_STATE_PROTECTED</strong> +<dd> +Send a <strong>catch_exception_raise_state</strong> message including the +thread state. Mark the exception port (and associated +exceptions) as protected. +<p> +<dt> <strong>EXCEPTION_STATE_IDENTITY</strong> +<dd> +Send a <strong>catch_exception_raise_state_identity</strong> message +including the thread identity and state. +<p> +<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong> +<dd> +Send a <strong>catch_exception_raise_state_identity</strong> message +including the thread identity and state. Mark the exception port +(and associated exceptions) as protected. +</dl> +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of state to be sent with the exception message. +These types are defined in \*L<mach/thread_states.h>\*O. +<p> +<dt> <var>old_exception_masks</var> +<dd> +[out array of <var>exception_mask_t</var>] +An array, each element being a mask +specifying for which exception types the corresponding element of the +other arrays apply. +<p> +<dt> <var>old_exception_count</var> +<dd> +[pointer to in/out scalar] +On input, the maximum size of the array +buffers; on output, the number of returned <exception type mask, +exception port, behavior, flavor> sets returned. +<p> +<dt> <var>old_exception_ports</var> +<dd> +[out array of exception send rights] +The returned exception ports. +<p> +<dt> <var>old_behaviors</var> +<dd> +[out array of <var>exception_behavior_t</var>] +The type of exception message to +be sent as with <var>behavior</var>. +<p> +<dt> <var>old_flavors</var> +<dd> +[out array of <var>thread_state_flavor_t</var>] +The type of state to be sent with +the exception message. These types are defined in +\*L<mach/thread_states.h>\*O. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_swap_exception_ports</strong> function sets a specified +set of exception +ports belonging to <var>thread</var>, returning the old set. +<h3>NOTES</h3> +<p> +If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is +the host name port, Mach kernel traps are executed by the kernel as expected; +any other value causes the attempted execution of these system call numbers to +be considered an exception. +<p> +A "protected" exception port is one which cannot be fetched and for which +exception processing cannot be aborted (<strong>thread_abort</strong>). +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_EXCEPTION_PROTECTED</strong> +<dd> +One of the requested exception ports is protected and cannot be returned. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>, +<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, +<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, +<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, +<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, +<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>, +<a href="thread_abort.html"><strong>thread_abort</strong></a>. diff --git a/osfmk/man/VSD_memory_manager.html b/osfmk/man/VSD_memory_manager.html index 7a1043334..28e81f333 100755 --- a/osfmk/man/VSD_memory_manager.html +++ b/osfmk/man/VSD_memory_manager.html @@ -1 +1,44 @@ -<h2>vm_set_default_memory_manager</h2> <hr> <p> <strong>Function</strong> - Obsolete interface. Functionality now provided via host_set_default_memory_manager interface.<h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_set_default_memory_manager</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>mach_port_move_send_t</strong> <var>default_manager</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control send right] The control port naming the host for which the default memory manager is to be set. <p> <dt> <var>default_manager</var> <dd> [pointer to in/out default-pager send right] A memory manager port to the new default memory manager. If this value is <strong>MACH_PORT_NULL</strong>, the old memory manager is not changed. The old memory manager port is returned in this variable. </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_set_default_memory_manager</strong> function establishes the default memory manager for a host. The named manager will be the target for future <strong>memory_object_create</strong> calls. <h3>NOTES</h3> The <strong>vm_set_default_memory_manager</strong> interface has been renamed to <strong>host_default_memory_manager</strong>. The old <strong>vm_set_default_memory_manager</strong> interface has been retained for backward compatibility, without the <var>cluster_size</var> parameter. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_create.html"><strong>memory_object_create</strong></a>, <a href="vm_allocate.html"><strong>vm_allocate</strong></a>. \ No newline at end of file +<h2>vm_set_default_memory_manager</h2> +<hr> +<p> +<strong>Function</strong> - Obsolete interface. Functionality now provided via host_set_default_memory_manager interface.<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_set_default_memory_manager</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>mach_port_move_send_t</strong> <var>default_manager</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The control port naming the host for which +the default memory manager is to be set. +<p> +<dt> <var>default_manager</var> +<dd> +[pointer to in/out default-pager send right] +A memory manager port to +the new default memory manager. If this value is <strong>MACH_PORT_NULL</strong>, +the old memory manager is not changed. The old memory +manager port is returned in this variable. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_set_default_memory_manager</strong> function establishes the default +memory manager for a host. The named manager will be the target for future +<strong>memory_object_create</strong> calls. +<h3>NOTES</h3> +The <strong>vm_set_default_memory_manager</strong> interface has been +renamed to <strong>host_default_memory_manager</strong>. The old +<strong>vm_set_default_memory_manager</strong> interface has been retained +for backward compatibility, without the <var>cluster_size</var> parameter. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_create.html"><strong>memory_object_create</strong></a>, +<a href="vm_allocate.html"><strong>vm_allocate</strong></a>. diff --git a/osfmk/man/bootstrap_arguments.html b/osfmk/man/bootstrap_arguments.html index 0b62fd7f8..c6c81db78 100755 --- a/osfmk/man/bootstrap_arguments.html +++ b/osfmk/man/bootstrap_arguments.html @@ -1 +1,56 @@ -<h2>bootstrap_arguments</h2> <hr> <p> <strong>Function</strong> - Return a set of arguments to the bootstrap task. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t bootstrap_arguments</strong> <strong>(mach_port_t</strong> <var>bootstrap</var>, <strong>task_t</strong> <var>task</var>, <strong>pointer_t</strong> <var>pointer_t</var>, <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>bootstrap</var> <dd> [in bootstrap send right] The bootstrap port for the task, obtained from <strong>task_get_special_ports</strong>. <p> <dt> <var>task</var> <dd> [in task send right] The task port for the task whose argument strings are requested. <p> <dt> <var>arguments</var> <dd> [pointer to dynamic out array of characters] The argument strings for the task. This is an array of <var>argumentCnt</var> bytes, containing NUL characters separating the strings. <p> <dt> <var>argumentsCnt</var> <dd> [out pointer to scalar] Number of bytes contained in <var>arguments</var>. </dl> <h3>DESCRIPTION</h3> <p> The kernel will respond to the bootstrap task (task 1) with the arguments and environment specified to the boot loader. The bootstrap task can act as a server on this interface for the tasks that it creates in order to pass arguments to them. The <strong>libsa_mach.a</strong> standalone Mach C runtime startup code uses <strong>bootstrap_arguments</strong> and <strong>bootstrap_environment</strong> to initialize <var>argc</var>, <var>argv</var>, and <var>envp</var> for <strong>main</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>, <a href="bootstrap_environment.html"><strong>bootstrap_environment</strong></a>. \ No newline at end of file +<h2>bootstrap_arguments</h2> +<hr> +<p> +<strong>Function</strong> - Return a set of arguments to the bootstrap task. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t bootstrap_arguments</strong> + <strong>(mach_port_t</strong> <var>bootstrap</var>, + <strong>task_t</strong> <var>task</var>, + <strong>pointer_t</strong> <var>pointer_t</var>, + <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>bootstrap</var> +<dd> +[in bootstrap send right] +The bootstrap port for the task, obtained from +<strong>task_get_special_ports</strong>. +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task port for the task whose argument strings are requested. +<p> +<dt> <var>arguments</var> +<dd> +[pointer to dynamic out array of characters] +The argument strings for the task. This is an array of +<var>argumentCnt</var> bytes, containing NUL characters +separating the strings. +<p> +<dt> <var>argumentsCnt</var> +<dd> +[out pointer to scalar] +Number of bytes contained in <var>arguments</var>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The kernel will respond to the bootstrap task (task 1) with the +arguments and environment specified to the boot loader. The bootstrap +task can act as a server on this interface for the tasks that it +creates in order to pass arguments to them. The <strong>libsa_mach.a</strong> +standalone Mach C runtime startup code uses <strong>bootstrap_arguments</strong> and +<strong>bootstrap_environment</strong> to initialize <var>argc</var>, <var>argv</var>, +and <var>envp</var> for <strong>main</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>, +<a href="bootstrap_environment.html"><strong>bootstrap_environment</strong></a>. + diff --git a/osfmk/man/bootstrap_completed.html b/osfmk/man/bootstrap_completed.html index 74da3ed71..99821368e 100755 --- a/osfmk/man/bootstrap_completed.html +++ b/osfmk/man/bootstrap_completed.html @@ -1 +1,59 @@ -<h2>bootstrap_completed</h2> <hr> <p> <strong>Server Interface</strong> - Inform bootstrap server that initialization is complete. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t bootstrap_completed</strong> <strong>(mach_port_t</strong> <var>bootstrap_port</var>, <strong>task_t</strong> <var>task</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>bootstrap_port</var> <dd> The port representing the calling task's bootstrap server. <p> <dt> <var>task</var> <dd> This parameter represents the calling task. </dl> <h3>DESCRIPTION</h3> <p> This interface allows a given server task to inform the bootstrap server that it is fully initialized and ready to handle requests. Upon receiving such notification, the bootstrap server can initialize any additional servers that may require services provided by the previously initialized server. <p> Note the following: not all servers that may be invoked by the bootstrap server send this message upon startup. If the bootstrap server is told to wait for this message before spawning further servers (via setting a flag in the <strong>bootstrap.conf</strong> file) and the server just invoked never sends this message, the bootstrap server will wait forever. <h3>NOTES</h3> <p> Currently, this interface is used exclusively by the default pager server so that the bootstrap server can defer initializing the OS server until the default pager is in place. (In small memory configurations, an OS server may not be able to initialize successfully unless the default pager is ready to handle paging requests.) <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The bootstrap server has updated the calling server's state with respect to bootstrap completion. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The bootstrap server does not recognize the calling server (the task specified by the <var>task</var> parameter). </dl> <h3>RELATED INFORMATION</h3> <p> Functions: \ No newline at end of file +<h2>bootstrap_completed</h2> +<hr> +<p> +<strong>Server Interface</strong> - Inform bootstrap server that +initialization is complete. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t bootstrap_completed</strong> + <strong>(mach_port_t</strong> <var>bootstrap_port</var>, + <strong>task_t</strong> <var>task</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>bootstrap_port</var> +<dd> +The port representing the calling task's bootstrap server. +<p> +<dt> <var>task</var> +<dd> +This parameter represents the calling task. +</dl> +<h3>DESCRIPTION</h3> +<p> +This interface allows a given server task to inform the bootstrap +server that it is fully initialized and ready to handle requests. +Upon receiving such notification, the bootstrap server can initialize +any additional servers that may require services provided by the +previously initialized server. +<p> +Note the following: not all servers that may be invoked by the bootstrap server +send this message upon startup. If the bootstrap server is told to +wait for this message before spawning further servers (via setting a +flag in the <strong>bootstrap.conf</strong> file) and the server just invoked never +sends this message, the bootstrap server will wait forever. +<h3>NOTES</h3> +<p> +Currently, this interface is used exclusively by the default +pager server so that the bootstrap server can defer initializing the +OS server until the default pager is in place. (In small memory +configurations, an OS server may not be able to initialize +successfully unless the default pager is ready to handle paging +requests.) +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The bootstrap server has updated the calling server's state with +respect to bootstrap completion. +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The bootstrap server does not recognize the calling server (the task +specified by the <var>task</var> parameter). +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: diff --git a/osfmk/man/bootstrap_environment.html b/osfmk/man/bootstrap_environment.html index 1b06e73c7..b7e531bb0 100755 --- a/osfmk/man/bootstrap_environment.html +++ b/osfmk/man/bootstrap_environment.html @@ -1 +1,56 @@ -<h2>bootstrap_environment</h2> <hr> <p> <strong>Function</strong> - Return to the bootstrap task an array of strings specifying the task's environment. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t bootstrap_environment</strong> <strong>(mach_port_t</strong> <var>bootstrap</var>, <strong>task_t</strong> <var>task</var>, <strong>pointer_t</strong> <var>pointer_t</var>, <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>bootstrap</var> <dd> [in bootstrap send right] The bootstrap port for the task, obtained from <strong>task_get_special_ports</strong>. <p> <dt> <var>task</var> <dd> [in task send right] The task port for the task whose argument strings are requested. <p> <dt> <var>environment</var> <dd> [pointer to dynamic out array of characters] The environment strings for the task. This is an array of \*V*_environmentCnt_\*O bytes, containing NUL characters separating the strings. <p> <dt> <var>environmentCnt</var> <dd> [out pointer to scalar] Number of bytes contained in <var>_environment_</var>. </dl> <h3>DESCRIPTION</h3> The kernel will respond to the bootstrap task (task 1) with the arguments and environment specified to the boot loader. The bootstrap task can act as a server on this interface for the tasks that it creates in order to pass an environment to them. The \*Llibsa_mach.a\*O standalone Mach C runtime startup code uses <strong>bootstrap_arguments</strong> and <strong>bootstrap_environment</strong> to initialize <var>argc</var>, <var>argv</var>, and <var>envp</var> for <strong>main</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>, <a href="bootstrap_arguments.html"><strong>bootstrap_arguments</strong></a>. \ No newline at end of file +<h2>bootstrap_environment</h2> +<hr> +<p> +<strong>Function</strong> - Return to the bootstrap task an array of strings specifying the task's environment. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t bootstrap_environment</strong> + <strong>(mach_port_t</strong> <var>bootstrap</var>, + <strong>task_t</strong> <var>task</var>, + <strong>pointer_t</strong> <var>pointer_t</var>, + <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>bootstrap</var> +<dd> +[in bootstrap send right] +The bootstrap port for the task, obtained from +<strong>task_get_special_ports</strong>. +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task port for the task whose argument strings are requested. +<p> +<dt> <var>environment</var> +<dd> +[pointer to dynamic out array of characters] +The environment strings for the task. This is an array of +\*V*_environmentCnt_\*O bytes, containing NUL characters +separating the strings. +<p> +<dt> <var>environmentCnt</var> +<dd> +[out pointer to scalar] +Number of bytes contained in <var>_environment_</var>. +</dl> +<h3>DESCRIPTION</h3> +The kernel will respond to the bootstrap task (task 1) with the +arguments and environment specified to the boot loader. The bootstrap +task can act as a server on this interface for the tasks that it +creates in order to pass an environment to them. The \*Llibsa_mach.a\*O +standalone Mach C runtime startup code uses <strong>bootstrap_arguments</strong> and +<strong>bootstrap_environment</strong> to initialize <var>argc</var>, <var>argv</var>, +and <var>envp</var> for <strong>main</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>, +<a href="bootstrap_arguments.html"><strong>bootstrap_arguments</strong></a>. + + diff --git a/osfmk/man/bootstrap_ports.html b/osfmk/man/bootstrap_ports.html index 3d5030e00..1b5b2fe1a 100755 --- a/osfmk/man/bootstrap_ports.html +++ b/osfmk/man/bootstrap_ports.html @@ -1 +1,75 @@ -<h2>bootstrap_ports</h2> <hr> <p> <strong>Function</strong> - Return send rights to the system's control ports. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t bootstrap_ports</strong> <strong>(mach_port_t</strong> <var>bootstrap</var>, <strong>bootstrap</strong> <var>host_control</var>, <strong>host_control</strong> <var>device_master</var>, <strong>device_master</strong> <var>root_wired_ledger</var>, <strong>root_wired_ledger</strong> <var>root_paged_ledger</var>, <strong>bootstrap</strong> <var>security</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>bootstrap</var> <dd> [in bootstrap send right] The bootstrap port obtained from \*Ltask_get_special_ports()\*O. <p> <dt> <var>host_priv</var> <dd> [out host-control send right] The control port for the host. <p> <dt> <var>device_master</var> <dd> [out device-master send right] The device master port. <p> <dt> <var>root_wired_ledger</var> <dd> [out ledger send right] The root wired kernel memory ledger port. <p> <dt> <var>root_paged_ledger</var> <dd> [out ledger send right] The root default memory managed space ledger port. <p> <dt> <var>security</var> <dd> [out security send right] The host security port, used for setting task identity. </dl> <h3>DESCRIPTION</h3> <p> The <strong>bootstrap_ports</strong> function returns a send right to the host control, root ledger, host security and device master ports. The kernel will respond to this message on the <strong>TASK_BOOTSTRAP_PORT</strong> given to the system bootstrap task (task 1) with the system privileged ports. It is the responsibility of the bootstrap task to manage the distribution of these rights to other servers. <p> An OS personality can serve as a server on the TASK_BOOTSTRAP_PORT for tasks or servers that it manages, and can regulate or interpose on the ports in any way it deems necessary. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_open.html"><strong>device_open</strong></a>, <a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>, <a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, <a href="host_processor_set_priv.html"><strong>host_processor_set_priv</strong></a>, <a href="host_processors.html"><strong>host_processors</strong></a>, <a href="ledger_create.html"><strong>ledger_create</strong></a>, <a href="task_set_security_token.html"><strong>task_set_security_token</strong></a>. \ No newline at end of file +<h2>bootstrap_ports</h2> +<hr> +<p> +<strong>Function</strong> - Return send rights to the system's control ports. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t bootstrap_ports</strong> + <strong>(mach_port_t</strong> <var>bootstrap</var>, + <strong>bootstrap</strong> <var>host_control</var>, + <strong>host_control</strong> <var>device_master</var>, + <strong>device_master</strong> <var>root_wired_ledger</var>, + <strong>root_wired_ledger</strong> <var>root_paged_ledger</var>, + <strong>bootstrap</strong> <var>security</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>bootstrap</var> +<dd> +[in bootstrap send right] +The bootstrap port obtained from \*Ltask_get_special_ports()\*O. +<p> +<dt> <var>host_priv</var> +<dd> +[out host-control send right] +The control port for the host. +<p> +<dt> <var>device_master</var> +<dd> +[out device-master send right] +The device master port. +<p> +<dt> <var>root_wired_ledger</var> +<dd> +[out ledger send right] +The root wired kernel memory ledger port. +<p> +<dt> <var>root_paged_ledger</var> +<dd> +[out ledger send right] +The root default memory managed space ledger +port. +<p> +<dt> <var>security</var> +<dd> +[out security send right] +The host security port, used for setting task +identity. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>bootstrap_ports</strong> function returns a send right to +the host control, root +ledger, host security and device master ports. The kernel will respond +to this message on the <strong>TASK_BOOTSTRAP_PORT</strong> given to the system bootstrap +task (task 1) with the system privileged ports. It is the +responsibility of the bootstrap task to manage the distribution +of these rights to other servers. +<p> +An OS personality can serve as a server on the TASK_BOOTSTRAP_PORT +for tasks or servers that it manages, and can regulate or interpose on +the ports in any way it deems necessary. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_open.html"><strong>device_open</strong></a>, +<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>, +<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, +<a href="host_processor_set_priv.html"><strong>host_processor_set_priv</strong></a>, +<a href="host_processors.html"><strong>host_processors</strong></a>, +<a href="ledger_create.html"><strong>ledger_create</strong></a>, +<a href="task_set_security_token.html"><strong>task_set_security_token</strong></a>. diff --git a/osfmk/man/catch_exception_raise.html b/osfmk/man/catch_exception_raise.html index 9a1c3b19a..9aafbb4df 100755 --- a/osfmk/man/catch_exception_raise.html +++ b/osfmk/man/catch_exception_raise.html @@ -1 +1,241 @@ -<h2>catch_exception_raise</h2> <hr> <p> <strong>Server Interface</strong> - Handles the occurrence of an exception within a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t catch_exception_raise</strong> <strong>(mach_port_t</strong> <var>exception_port</var>, <strong>mach_port_t</strong> <var>thread</var>, <strong>mach_port_t</strong> <var>task</var>, <strong>exception_type_t</strong> <var>exception</var>, <strong>exception_data_t</strong> <var>code</var>, <strong>mach_msg_type_number_t</strong> <var>code_count</var><strong>);</strong> </pre> <p> <strong>catch_exception_raise_state</strong> expanded form: <pre> <strong>kern_return_t catch_exception_raise_state</strong> <strong>(mach_port_t</strong> <var>exception_port</var>, <strong>exception_type_t</strong> <var>exception</var>, <strong>exception_data_t</strong> <var>code</var>, <strong>mach_msg_type_number_t</strong> <var>code_count</var>, <strong>int *</strong> <var>flavor</var>, <strong>thread_state_t</strong> <var>in_state</var>, <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>, <strong>thread_state_t</strong> <var>out_state</var>, <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong> </pre> <p> <strong>catch_exception_raise_state_identity</strong> expanded form: <pre> <strong>kern_return_t catch_exception_raise_state_identity</strong> <strong>(mach_port_t</strong> <var>exception_port</var>, <strong>mach_port_t</strong> <var>thread</var>, <strong>mach_port_t</strong> <var>task</var>, <strong>exception_type_t</strong> <var>exception</var>, <strong>exception_data_t</strong> <var>code</var>, <strong>mach_msg_type_number_t</strong> <var>code_count</var>, <strong>int *</strong> <var>flavor</var>, <strong>thread_state_t</strong> <var>in_state</var>, <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>, <strong>thread_state_t</strong> <var>out_state</var>, <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>exception_port</var> <dd> [in exception (receive) right] The port to which the exception notification was sent. <p> <dt> <var>thread</var> <dd> [in thread-self send right] The thread self port for the thread taking the exception. <p> <dt> <var>task</var> <dd> [in task-self send right] The task self port for the task containing the thread taking the exception. <p> <dt> <var>exception</var> <dd> [in scalar] The type of the exception. The machine independent values raised by all implementations are: <dl> <p> <dt> EXC_BAD_ACCESS <dd> Could not access memory. subcode contains the bad memory address. <p> <dt> EXC_BAD_INSTRUCTION <dd> Instruction failed. Illegal or undefined instruction or operand. <p> <dt> EXC_ARITHMETIC <dd> Arithmetic exception; exact nature of exception is in subcode field. <p> <dt> EXC_EMULATION <dd> Emulation instruction. Emulation support instruction encountered. Details in subcode field. <p> <dt> EXC_SOFTWARE <dd> Software generated exception; exact exception is in subcode field. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000 - 0x1FFFF reserved for OS emulation. <p> <dt> EXC_BREAKPOINT <dd> Trace, breakpoint, etc. Details in subcode field. <p> <dt> EXC_SYSCALL <dd> System call requested. Details in subcode field. <p> <dt> EXC_MACH_SYSCALL <dd> System call with a number in the Mach call range requested. Details in subcode field. </dl <p> <dt> <var>code</var> <dd> [in scalar] A machine dependent array indicating a particular instance of exception. <p> <dt> <var>code_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). <p> <dt> <var>flavor</var> <dd> [pointer to in/out scalar] On input, the type of state included as selected when the exception port was set. On output, the type of state being returned. <p> <dt> <var>in_state</var> <dd> [pointer to in structure] State information of the thread at the time of the exception. <p> <dt> <var>in_state_count</var> <dd> [in scalar] The size of the in state buffer (in natural-sized units). <p> <dt> <var>out_state</var> <dd> [out structure] The state the thread will have if continued from the point of the exception. The maximum size of this array is THREAD_STATE_MAX. <p> <dt> <var>out_state_count</var> <dd> [pointer to out scalar] The size of the out state buffer (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> A <strong>catch_exception_raise</strong> function is called by <strong>exc_server</strong> as the result of a kernel message indicating that an exception occurred within a thread. The <var>exception_port</var> parameter specifies the port named via a previous call to <strong>thread_set_exception_ports</strong> or <strong>task_set_exception_ports</strong> as the port that responds when the thread takes an exception. <p> The alternate message forms (the format being selected when the exception port was set) allow for selected thread state to be included. <h3>NOTES</h3> <p> When an exception occurs in a thread, the thread sends an exception message to its exception port, blocking in the kernel waiting for the receipt of a reply. It is assumed that some task is listening (most likely with <strong>mach_msg_server</strong>) to this port, using the <strong>exc_server</strong> function to decode the messages and then call the linked in <strong>catch_exception_raise</strong>. It is the job of <strong>catch_exception_raise</strong> to handle the exception and decide the course of action for thread. <p> If the thread should continue from the point of exception, <strong>catch_exception_raise</strong> would return KERN_SUCCESS. This causes a reply message to be sent to the kernel, which will allow the thread to continue from the point of the exception. If some other action should be taken by thread, the following actions should be performed by <strong>catch_exception_raise</strong>: <dl> <dt> <strong>thread_suspend</strong> <dd> This keeps the thread from proceeding after the next step. <p> <dt> <strong>thread_abort</strong> <dd> This aborts the message receive operation currently blocking the thread. <p> <dt> <strong>thread_set_state</strong> <dd> (if using the <strong>catch_exception_raise</strong> form). Set the thread's state so that it continues doing something else. <p> <dt> <strong>thread_resume</strong> <dd> Let the thread start running from its new state. </dl> Returning a value other than KERN_SUCCESS insures that no reply message will be sent. sent. (Actually, the kernel uses a send once right to send the exception message, which <strong>thread_abort</strong> destroys, so replying to the message is harmless.) The thread can always be destroyed with <strong>thread_terminate</strong>. <p> A thread can have two exception ports active for it: its thread type specific exception port and the task type specific exception port. The kernel will try sending an exception message to both ports looking for a reply message with a return value of KERN_SUCCESS. The kernel tries the thread specific port first, then the task specific port. If the return value from the first exception message the kernel sends has a return value of KERN_SUCCESS, the thread continues (with a possibly modified state). If the return value is not KERN_SUCCESS, the kernel tries the second port. If that return value is KERN_SUCCESS, the thread continues; otherwise, the thread is terminated. <p> To get the effect of a non-success return value, the server interface should return MIG_DESTROY_REQUEST. This causes <strong>exc_server</strong> and <strong>mach_msg_server</strong> to destroy the kernel's request (as opposed to sending a reply with a KERN_SUCCESS value). <h3>RETURN VALUES</h3> <p> A return value of KERN_SUCCESS indicates that the thread is to continue from the point of exception. A return value of MIG_NO_REPLY indicates that the exception was handled directly and the thread was restarted or terminated by the exception handler. A return value of MIG_DESTROY_REQUEST causes the kernel to try another exception handler (or terminate the thread). Any other value will cause <strong>mach_msg_server</strong> to remove the task and thread port references. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="exc_server.html"><strong>exc_server</strong></a>, <a href="thread_abort.html"><strong>thread_abort</strong></a>, <a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, <a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, <a href="thread_get_state.html"><strong>thread_get_state</strong></a>, <a href="thread_resume.html"><strong>thread_resume</strong></a>, <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, <a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, <a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, <a href="thread_set_state.html"><strong>thread_set_state</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>, <a href="thread_terminate.html"><strong>thread_terminate</strong></a>. \ No newline at end of file +<h2>catch_exception_raise</h2> +<hr> +<p> +<strong>Server Interface</strong> - Handles the occurrence of an exception within a thread. + +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t catch_exception_raise</strong> + <strong>(mach_port_t</strong> <var>exception_port</var>, + <strong>mach_port_t</strong> <var>thread</var>, + <strong>mach_port_t</strong> <var>task</var>, + <strong>exception_type_t</strong> <var>exception</var>, + <strong>exception_data_t</strong> <var>code</var>, + <strong>mach_msg_type_number_t</strong> <var>code_count</var><strong>);</strong> +</pre> +<p> +<strong>catch_exception_raise_state</strong> +expanded form: +<pre> +<strong>kern_return_t catch_exception_raise_state</strong> + <strong>(mach_port_t</strong> <var>exception_port</var>, + <strong>exception_type_t</strong> <var>exception</var>, + <strong>exception_data_t</strong> <var>code</var>, + <strong>mach_msg_type_number_t</strong> <var>code_count</var>, + <strong>int *</strong> <var>flavor</var>, + <strong>thread_state_t</strong> <var>in_state</var>, + <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>, + <strong>thread_state_t</strong> <var>out_state</var>, + <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong> +</pre> +<p> +<strong>catch_exception_raise_state_identity</strong> +expanded form: +<pre> +<strong>kern_return_t catch_exception_raise_state_identity</strong> + <strong>(mach_port_t</strong> <var>exception_port</var>, + <strong>mach_port_t</strong> <var>thread</var>, + <strong>mach_port_t</strong> <var>task</var>, + <strong>exception_type_t</strong> <var>exception</var>, + <strong>exception_data_t</strong> <var>code</var>, + <strong>mach_msg_type_number_t</strong> <var>code_count</var>, + <strong>int *</strong> <var>flavor</var>, + <strong>thread_state_t</strong> <var>in_state</var>, + <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>, + <strong>thread_state_t</strong> <var>out_state</var>, + <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>exception_port</var> +<dd> +[in exception (receive) right] The port to which the exception +notification was sent. +<p> +<dt> <var>thread</var> +<dd> +[in thread-self send right] The thread self port for the thread taking the +exception. +<p> +<dt> <var>task</var> +<dd> +[in task-self send right] The task self port for the task containing the +thread taking the exception. +<p> +<dt> <var>exception</var> +<dd> +[in scalar] The type of the exception. +The machine independent values raised by all implementations are: + <dl> +<p> +<dt> EXC_BAD_ACCESS +<dd> +Could not access memory. subcode contains the bad memory +address. +<p> +<dt> EXC_BAD_INSTRUCTION +<dd> +Instruction failed. Illegal or undefined instruction or operand. +<p> +<dt> EXC_ARITHMETIC +<dd> +Arithmetic exception; exact nature of exception is in subcode +field. +<p> +<dt> EXC_EMULATION +<dd> +Emulation instruction. Emulation support instruction encountered. +Details in subcode field. +<p> +<dt> EXC_SOFTWARE +<dd> +Software generated exception; exact exception is in subcode +field. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000 +- 0x1FFFF reserved for OS emulation. +<p> +<dt> EXC_BREAKPOINT +<dd> +Trace, breakpoint, etc. Details in subcode field. +<p> +<dt> EXC_SYSCALL +<dd> +System call requested. Details in subcode field. +<p> +<dt> EXC_MACH_SYSCALL +<dd> +System call with a number in the Mach call range requested. +Details in subcode field. + </dl +<p> +<dt> <var>code</var> +<dd> +[in scalar] A machine dependent array indicating a particular instance +of exception. +<p> +<dt> <var>code_count</var> +<dd> +[in scalar] The size of the buffer (in natural-sized units). +<p> +<dt> <var>flavor</var> +<dd> +[pointer to in/out scalar] On input, the type of state included as selected +when the exception port was set. On output, the type of state being +returned. +<p> +<dt> <var>in_state</var> +<dd> +[pointer to in structure] State information of the thread at the time of +the exception. +<p> +<dt> <var>in_state_count</var> +<dd> +[in scalar] The size of the in state buffer (in natural-sized units). +<p> +<dt> <var>out_state</var> +<dd> +[out structure] The state the thread will have if continued from the +point of the exception. The maximum size of this array is +THREAD_STATE_MAX. +<p> +<dt> <var>out_state_count</var> +<dd> +[pointer to out scalar] The size of the out state buffer (in natural-sized units). + </dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>catch_exception_raise</strong> function is called by +<strong>exc_server</strong> as the result of a +kernel message indicating that an exception occurred within a thread. +The <var>exception_port</var> parameter specifies the port named via +a previous call to <strong>thread_set_exception_ports</strong> or +<strong>task_set_exception_ports</strong> +as the port that responds when the thread takes an +exception. +<p> +The alternate message forms (the format being selected when the exception port +was set) allow for selected thread state to be included. + +<h3>NOTES</h3> +<p> +When an exception occurs in a thread, the thread sends an exception message to +its exception port, blocking in the kernel waiting for the receipt of a reply. It is +assumed that some task is listening +(most likely with <strong>mach_msg_server</strong>) to this +port, using the <strong>exc_server</strong> function +to decode the messages and then call the +linked in <strong>catch_exception_raise</strong>. +It is the job of <strong>catch_exception_raise</strong> to handle +the exception and decide the course of action for thread. + <p> +If the thread should continue from the point of exception, +<strong>catch_exception_raise</strong> would return KERN_SUCCESS. This causes a reply +message to be sent to the kernel, which will allow the thread to continue from +the point of the exception. +If some other action should be taken by thread, the following actions should be +performed by <strong>catch_exception_raise</strong>: + <dl> + <dt> <strong>thread_suspend</strong> + <dd> + This keeps the thread from proceeding after the next step. + <p> +<dt> <strong>thread_abort</strong> + <dd> + This aborts the message receive operation currently blocking +the thread. + <p> +<dt> <strong>thread_set_state</strong> + <dd> + (if using the <strong>catch_exception_raise</strong> form). Set the +thread's state so that it continues doing something else. + <p> + <dt> <strong>thread_resume</strong> + <dd> + Let the thread start running from its new state. +</dl> +Returning a value other than KERN_SUCCESS insures that no reply message +will be sent. +sent. (Actually, the kernel uses a send once right to send the exception +message, which <strong>thread_abort</strong> destroys, so replying to the message is harmless.) +The thread can always be destroyed with <strong>thread_terminate</strong>. +<p> +A thread can have two exception ports active for it: its thread type specific exception +port and the task type specific exception port. The kernel will try sending +an exception message to both ports looking for a reply message with a +return value of KERN_SUCCESS. The kernel tries the thread specific port first, +then the task specific port. If the return value from the first exception message +the kernel sends has a return value of KERN_SUCCESS, the thread continues +(with a possibly modified state). If the return value is not KERN_SUCCESS, +the kernel tries the second port. If that return value is KERN_SUCCESS, the +thread continues; otherwise, the thread is terminated. +<p> +To get the effect of a non-success return value, the server interface should return +MIG_DESTROY_REQUEST. This causes <strong>exc_server</strong> and <strong>mach_msg_server</strong> +to destroy the kernel's request (as opposed to sending a reply with a +KERN_SUCCESS value). + +<h3>RETURN VALUES</h3> +<p> +A return value of KERN_SUCCESS indicates that the thread is to continue +from the point of exception. A return value of MIG_NO_REPLY indicates that +the exception was handled directly and the thread was restarted or terminated by +the exception handler. A return value of MIG_DESTROY_REQUEST causes +the kernel to try another exception handler (or terminate the thread). Any other +value will cause +<strong>mach_msg_server</strong> to remove the task and thread port references. + +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="exc_server.html"><strong>exc_server</strong></a>, +<a href="thread_abort.html"><strong>thread_abort</strong></a>, +<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, +<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, +<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, +<a href="thread_resume.html"><strong>thread_resume</strong></a>, +<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, +<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, +<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, +<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, +<a href="thread_set_state.html"><strong>thread_set_state</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>, +<a href="thread_terminate.html"><strong>thread_terminate</strong></a>. diff --git a/osfmk/man/clock_alarm.html b/osfmk/man/clock_alarm.html index 0c94b5803..935752c01 100755 --- a/osfmk/man/clock_alarm.html +++ b/osfmk/man/clock_alarm.html @@ -1 +1,79 @@ -<h2>clock_alarm</h2> <hr> <p> <strong>Function</strong> - Set off an alarm. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t clock_alarm</strong> <strong>(clock_t</strong> <var>clock_name</var>, <strong>alarm_type_t</strong> <var>alarm_type</var>, <strong>tvalspec_t</strong> <var>alarm_time</var>, <strong>mach_port_t</strong> <var>alarm_reply_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>clock_name</var> <dd> [in clock-name send right] The name (or control) port for the clock. <p> <dt> <var>alarm_type</var> <dd> [in scalar] How to interpret the <var>alarm_time</var> value: <dl> <p> <dt> <strong>TIME_RELATIVE</strong> <dd> Interpret the alarm time as relative to the current time. <p> <dt> <strong>TIME_ABSOLUTE</strong> <dd> Interpret the alarm time as an absolute time. </dl> <p> <dt> <var>alarm_time</var> <dd> [in structure] The time when the alarm is to be sent. <p> <dt> <var>alarm_reply_port</var> <dd> [in alarm receive (to be converted to send-once) right] A port into which the alarm message is to be sent. </dl> <h3>DESCRIPTION</h3> <p> The <strong>clock_alarm</strong> function requests that a clock send an alarm message to a specified port at a given future time. The alarm message is specified by the <strong>clock_alarm_reply</strong> server interface. <h3>NOTES</h3> <p> If the specified alarm time is in the past, the alarm message is sent immediately and time-stamped with the current time. Otherwise, the alarm is queued and delivered at the specified alarm time and time-stamped at that time. <p> The alarm will be serviced at the service time nearest the specified alarm time as governed by the current clock alarm resolution. <p> Not all clocks implement this service, but the REALTIME clock must. If the clock does not provide this service, this call is ignored. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, <a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, <a href="clock_get_time.html"><strong>clock_get_time</strong></a>, <a href="clock_sleep.html"><strong>clock_sleep</strong></a>, <a href="clock_alarm_reply.html"><strong>clock_alarm_reply</strong></a>. <p> Data Structures: <a href="tvalspec.html"><strong>tvalspec</strong></a>. \ No newline at end of file +<h2>clock_alarm</h2> +<hr> +<p> +<strong>Function</strong> - Set off an alarm. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t clock_alarm</strong> + <strong>(clock_t</strong> <var>clock_name</var>, + <strong>alarm_type_t</strong> <var>alarm_type</var>, + <strong>tvalspec_t</strong> <var>alarm_time</var>, + <strong>mach_port_t</strong> <var>alarm_reply_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>clock_name</var> +<dd> +[in clock-name send right] +The name (or control) port for the clock. +<p> +<dt> <var>alarm_type</var> +<dd> +[in scalar] +How to interpret the <var>alarm_time</var> value: +<dl> +<p> +<dt> <strong>TIME_RELATIVE</strong> +<dd> +Interpret the alarm time as relative to the current time. +<p> +<dt> <strong>TIME_ABSOLUTE</strong> +<dd> +Interpret the alarm time as an absolute time. +</dl> +<p> +<dt> <var>alarm_time</var> +<dd> +[in structure] +The time when the alarm is to be sent. +<p> +<dt> <var>alarm_reply_port</var> +<dd> +[in alarm receive (to be converted to send-once) right] +A port into +which the alarm message is to be sent. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>clock_alarm</strong> function requests that a clock send +an alarm message to a +specified port at a given future time. The alarm message is specified by the +<strong>clock_alarm_reply</strong> server interface. +<h3>NOTES</h3> +<p> +If the specified alarm time is in the past, the alarm message +is sent immediately +and time-stamped with the current time. Otherwise, the alarm is queued and +delivered at the specified alarm time and time-stamped at that time. +<p> +The alarm will be serviced at the service time nearest the specified +alarm time +as governed by the current clock alarm resolution. +<p> +Not all clocks implement this service, but the REALTIME clock must. If the +clock does not provide this service, this call is ignored. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, +<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, +<a href="clock_get_time.html"><strong>clock_get_time</strong></a>, +<a href="clock_sleep.html"><strong>clock_sleep</strong></a>, +<a href="clock_alarm_reply.html"><strong>clock_alarm_reply</strong></a>. +<p> +Data Structures: +<a href="tvalspec.html"><strong>tvalspec</strong></a>. diff --git a/osfmk/man/clock_alarm_reply.html b/osfmk/man/clock_alarm_reply.html index 0b951e7c8..04b477954 100755 --- a/osfmk/man/clock_alarm_reply.html +++ b/osfmk/man/clock_alarm_reply.html @@ -1 +1,80 @@ -<h2>clock_alarm_reply</h2> <hr> <p> <strong>Function</strong> - Ring a preset alarm. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t clock_alarm_reply</strong> <strong>(reply_port_t</strong> <var>alarm_reply_port</var>, <strong>kern_return_t</strong> <var>reply_code</var>, <strong>alarm_type_t</strong> <var>alarm_type</var>, <strong>tvalspec_t</strong> <var>wake_time</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>alarm_reply_port</var> <dd> [in alarm (receive) right] The reply port named in the corresponding <strong>clock_alarm</strong> call. <p> <dt> <var>reply_code</var> <dd> [in scalar] The reply status code from the alarm. The possible values are: <dl> <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The alarm was delivered without problem. <p> <dt> <strong>KERN_INVALID_VALUE</strong> <dd> The <var>alarm_type</var> and/or <var>alarm_time</var> values supplied to <strong>clock_alarm</strong> were invalid. <p> <dt> <strong>KERN_INVALID_LEDGER</strong> <dd> The <var>ledger</var> supplied to <strong>clock_alarm</strong> was not a ledger. <p> <dt> <strong>KERN_ABORTED</strong> <dd> The alarm was terminated via use of <strong>clock_set_time</strong>. </dl> <p> <dt> <var>alarm_type</var> <dd> [in scalar] The alarm type value supplied to the <strong>clock_alarm</strong> call. Only the low order bits of this value are used by the kernel so the high order bits are available for application use as an alarm identifier. <p> <dt> <var>wake_time</var> <dd> [in structure] The time when the alarm message was sent. </dl> <h3>DESCRIPTION</h3> <p> A <strong>clock_alarm_reply</strong> function is called as the result of a message from the kernel indicating that a previously requested alarm time (<strong>clock_alarm</strong>) has arrived. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, <a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, <a href="clock_get_time.html"><strong>clock_get_time</strong></a>, <a href="clock_sleep.html"><strong>clock_sleep</strong></a>, <a href="clock_alarm.html"><strong>clock_alarm</strong></a>, <a href="clock_reply_server.html"><strong>clock_reply_server</strong></a>, <a href="clock_set_time.html"><strong>clock_set_time</strong></a>. <p> Data Structures: <a href="tvalspec.html"><strong>tvalspec</strong></a>. \ No newline at end of file +<h2>clock_alarm_reply</h2> +<hr> +<p> +<strong>Function</strong> - Ring a preset alarm. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t clock_alarm_reply</strong> + <strong>(reply_port_t</strong> <var>alarm_reply_port</var>, + <strong>kern_return_t</strong> <var>reply_code</var>, + <strong>alarm_type_t</strong> <var>alarm_type</var>, + <strong>tvalspec_t</strong> <var>wake_time</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>alarm_reply_port</var> +<dd> +[in alarm (receive) right] +The reply port named in the corresponding +<strong>clock_alarm</strong> call. +<p> +<dt> <var>reply_code</var> +<dd> +[in scalar] +The reply status code from the alarm. The possible values +are: +<dl> +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The alarm was delivered without problem. +<p> +<dt> <strong>KERN_INVALID_VALUE</strong> +<dd> +The <var>alarm_type</var> and/or <var>alarm_time</var> values supplied to +<strong>clock_alarm</strong> were invalid. +<p> +<dt> <strong>KERN_INVALID_LEDGER</strong> +<dd> +The <var>ledger</var> supplied to <strong>clock_alarm</strong> was not a ledger. +<p> +<dt> <strong>KERN_ABORTED</strong> +<dd> +The alarm was terminated via use of <strong>clock_set_time</strong>. +</dl> +<p> +<dt> <var>alarm_type</var> +<dd> +[in scalar] +The alarm type value supplied to the <strong>clock_alarm</strong> call. +Only the low order bits of this value are used by the kernel so the high +order bits are available for application use as an alarm identifier. +<p> +<dt> <var>wake_time</var> +<dd> +[in structure] +The time when the alarm message was sent. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>clock_alarm_reply</strong> function is called as the result +of a message from the +kernel indicating that a previously requested alarm time (<strong>clock_alarm</strong>) +has arrived. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, +<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, +<a href="clock_get_time.html"><strong>clock_get_time</strong></a>, +<a href="clock_sleep.html"><strong>clock_sleep</strong></a>, +<a href="clock_alarm.html"><strong>clock_alarm</strong></a>, +<a href="clock_reply_server.html"><strong>clock_reply_server</strong></a>, +<a href="clock_set_time.html"><strong>clock_set_time</strong></a>. +<p> +Data Structures: +<a href="tvalspec.html"><strong>tvalspec</strong></a>. diff --git a/osfmk/man/clock_get_attributes.html b/osfmk/man/clock_get_attributes.html index 62fecf084..2ece755a2 100755 --- a/osfmk/man/clock_get_attributes.html +++ b/osfmk/man/clock_get_attributes.html @@ -1 +1,79 @@ -<h2>clock_get_attributes</h2> <hr> <p> <strong>Function</strong> - Return attributes of a clock. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t clock_get_attributes</strong> <strong>(clock_t</strong> <var>clock_name</var>, <strong>clock_flavor_t</strong> <var>flavor</var>, <strong>clock_attr_t</strong> <var>attribute</var>, <strong>mach_msg_type_number_t</strong> <var>attribute_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>clock_name</var> <dd> [in clock-name send right] The name (or control) port for the clock. <p> <dt> <var>flavor</var> <dd> [in scalar] Type of information desired. Defined values are: <dl> <p> <dt> <strong>CLOCK_GET_TIME_RES</strong> <dd> The resolution, in nanoseconds, with which the value returned by <strong>clock_get_time</strong> is updated. <p> <dt> <strong>CLOCK_MAP_TIME_RES</strong> <dd> The resolution, in nanoseconds, with which the value visible via <strong>clock_map_time</strong> is updated. <p> <dt> <strong>CLOCK_ALARM_CURRES</strong> <dd> The resolution, in nanoseconds, at which clock alarm and sleep timers are currently serviced. <p> <dt> <strong>CLOCK_ALARM_MINRES</strong> <dd> The minimum resolution, in nanoseconds, at which clock alarm and sleep timers can be serviced. <p> <dt> <strong>CLOCK_ALARM_MAXRES</strong> <dd> The maximum resolution, in nanoseconds, at which clock alarm and sleep timers can be serviced. </dl> <p> <dt> <var>attribute</var> <dd> [out scalar] The returned attribute. <p> <dt> <var>attribute_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>clock_get_attributes</strong> function returns attributes of a clock's implementation or operation. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, <a href="clock_get_time.html"><strong>clock_get_time</strong></a>, <a href="clock_map_time.html"><strong>clock_map_time</strong></a>, <a href="clock_sleep.html"><strong>clock_sleep</strong></a>, <a href="clock_alarm.html"><strong>clock_alarm</strong></a>, <a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>. \ No newline at end of file +<h2>clock_get_attributes</h2> +<hr> +<p> +<strong>Function</strong> - Return attributes of a clock. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t clock_get_attributes</strong> + <strong>(clock_t</strong> <var>clock_name</var>, + <strong>clock_flavor_t</strong> <var>flavor</var>, + <strong>clock_attr_t</strong> <var>attribute</var>, + <strong>mach_msg_type_number_t</strong> <var>attribute_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>clock_name</var> +<dd> +[in clock-name send right] +The name (or control) port for the clock. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +Type of information desired. Defined values are: +<dl> +<p> +<dt> <strong>CLOCK_GET_TIME_RES</strong> +<dd> +The resolution, in nanoseconds, with which the value returned +by <strong>clock_get_time</strong> is updated. +<p> +<dt> <strong>CLOCK_MAP_TIME_RES</strong> +<dd> +The resolution, in nanoseconds, with which the value visible +via <strong>clock_map_time</strong> is updated. +<p> +<dt> <strong>CLOCK_ALARM_CURRES</strong> +<dd> +The resolution, in nanoseconds, at which clock alarm and +sleep timers are currently serviced. +<p> +<dt> <strong>CLOCK_ALARM_MINRES</strong> +<dd> +The minimum resolution, in nanoseconds, at which clock +alarm and sleep timers can be serviced. +<p> +<dt> <strong>CLOCK_ALARM_MAXRES</strong> +<dd> +The maximum resolution, in nanoseconds, at which clock +alarm and sleep timers can be serviced. +</dl> +<p> +<dt> <var>attribute</var> +<dd> +[out scalar] +The returned attribute. +<p> +<dt> <var>attribute_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>clock_get_attributes</strong> function returns attributes of a clock's +implementation or operation. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, +<a href="clock_get_time.html"><strong>clock_get_time</strong></a>, +<a href="clock_map_time.html"><strong>clock_map_time</strong></a>, +<a href="clock_sleep.html"><strong>clock_sleep</strong></a>, +<a href="clock_alarm.html"><strong>clock_alarm</strong></a>, +<a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>. diff --git a/osfmk/man/clock_get_time.html b/osfmk/man/clock_get_time.html index f1329d21f..238a426fc 100755 --- a/osfmk/man/clock_get_time.html +++ b/osfmk/man/clock_get_time.html @@ -1 +1,45 @@ -<h2>clock_get_time</h2> <hr> <p> <strong>Function</strong> - Return the current time. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t clock_get_time</strong> <strong>(clock_t</strong> <var>clock_name</var>, <strong>tvalspec_t</strong> <var>cur_time</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>clock_name</var> <dd> [in clock-name send right] The name (or control) port for the clock. <p> <dt> <var>cur_time</var> <dd> [out structure] Current time </dl> <h3>DESCRIPTION</h3> <p> The <strong>clock_get_time</strong> function returns the current time kept by a clock. The value returned is a monotonically increasing value (unless tampered with via the <strong>clock_set_time</strong> function). <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, <a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, <a href="clock_map_time.html"><strong>clock_map_time</strong></a>, <a href="clock_sleep.html"><strong>clock_sleep</strong></a>, <a href="clock_alarm.html"><strong>clock_alarm</strong></a>, <a href="clock_set_time.html"><strong>clock_set_time</strong></a>. <p> Data Structures: <a href="tvalspec.html"><strong>tvalspec</strong></a>. \ No newline at end of file +<h2>clock_get_time</h2> +<hr> +<p> +<strong>Function</strong> - Return the current time. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t clock_get_time</strong> + <strong>(clock_t</strong> <var>clock_name</var>, + <strong>tvalspec_t</strong> <var>cur_time</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>clock_name</var> +<dd> +[in clock-name send right] +The name (or control) port for the clock. +<p> +<dt> <var>cur_time</var> +<dd> +[out structure] +Current time +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>clock_get_time</strong> function returns the current time +kept by a clock. The +value returned is a monotonically increasing value (unless tampered +with via the +<strong>clock_set_time</strong> function). +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, +<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, +<a href="clock_map_time.html"><strong>clock_map_time</strong></a>, +<a href="clock_sleep.html"><strong>clock_sleep</strong></a>, +<a href="clock_alarm.html"><strong>clock_alarm</strong></a>, +<a href="clock_set_time.html"><strong>clock_set_time</strong></a>. +<p> +Data Structures: +<a href="tvalspec.html"><strong>tvalspec</strong></a>. diff --git a/osfmk/man/clock_map_time.html b/osfmk/man/clock_map_time.html index ce8fa4430..5859853b6 100755 --- a/osfmk/man/clock_map_time.html +++ b/osfmk/man/clock_map_time.html @@ -1 +1,51 @@ -<h2>clock_map_time</h2> <hr> <p> <strong>Function</strong> - Return a memory object that maps a clock. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t clock_map_time</strong> <strong>(clock_t</strong> <var>clock_name</var>, <strong>memory_object_t</strong> <var>clock_memory</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>clock_name</var> <dd> [in clock-name send right] The name (or control) port for the clock. <p> <dt> <var>clock_memory</var> <dd> [out memory-object-representative send right] Mapped clock time memory object representative. </dl> <h3>DESCRIPTION</h3> <p> The <strong>clock_map_time</strong> function returns a memory object representative port representing read access to a memory object that contains (at offset zero) a mapped version of the clock time (structure <strong>mapped_tvalspec</strong>). The returned right is suitable as an argument for <strong>vm_map</strong>. <h3>NOTES</h3> <p> Not all clocks provide this service, but the REALTIME clock must. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_FAILURE</strong> <dd> The specified clock does not provide this service. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, <a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, <a href="clock_get_time.html"><strong>clock_get_time</strong></a>, <a href="clock_sleep.html"><strong>clock_sleep</strong></a>, <a href="clock_alarm.html"><strong>clock_alarm</strong></a>. <p> Data Structures: <a href="mapped_tvalspec.html"><strong>mapped_tvalspec</strong></a>. \ No newline at end of file +<h2>clock_map_time</h2> +<hr> +<p> +<strong>Function</strong> - Return a memory object that maps a clock. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t clock_map_time</strong> + <strong>(clock_t</strong> <var>clock_name</var>, + <strong>memory_object_t</strong> <var>clock_memory</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>clock_name</var> +<dd> +[in clock-name send right] +The name (or control) port for the clock. +<p> +<dt> <var>clock_memory</var> +<dd> +[out memory-object-representative send right] +Mapped clock time +memory object representative. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>clock_map_time</strong> function returns a memory object representative port +representing read access to a memory object that contains (at offset zero) a +mapped version of the clock time (structure <strong>mapped_tvalspec</strong>). +The returned right is suitable as an argument for <strong>vm_map</strong>. +<h3>NOTES</h3> +<p> +Not all clocks provide this service, but the REALTIME clock must. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_FAILURE</strong> +<dd> +The specified clock does not provide this service. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, +<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, +<a href="clock_get_time.html"><strong>clock_get_time</strong></a>, +<a href="clock_sleep.html"><strong>clock_sleep</strong></a>, +<a href="clock_alarm.html"><strong>clock_alarm</strong></a>. +<p> +Data Structures: +<a href="mapped_tvalspec.html"><strong>mapped_tvalspec</strong></a>. diff --git a/osfmk/man/clock_reply_server.html b/osfmk/man/clock_reply_server.html index 08599b141..2f7d36a33 100755 --- a/osfmk/man/clock_reply_server.html +++ b/osfmk/man/clock_reply_server.html @@ -1 +1,49 @@ -<h2>clock_reply_server</h2> <hr> <p> <strong>Function</strong> - Handle kernel-generated alarm. <h3>SYNOPSIS</h3> <pre> <strong>boolean_t clock_reply_server</strong> <strong>(mach_msg_header_t</strong> <var>request_msg</var>, <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>in_msg</var> <dd> [pointer to in structure] The alarm message received from the kernel. <p> <dt> <var>out_msg</var> <dd> [out structure] Not used. </dl> <h3>DESCRIPTION</h3> <p> The <strong>clock_reply_server</strong> function is the MIG generated server handling function to handle messages from the kernel corresponding to clock alarms. Such messages are delivered to the alarm reply port named in a <strong>clock_alarm</strong> call. The <strong>clock_reply_server</strong> function performs all necessary argument handling for this kernel message and calls the appropriate handling function. These functions must be supplied by the caller. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>TRUE</strong> <dd> The message was handled and the appropriate function was called. <p> <dt> <strong>FALSE</strong> <dd> The message did not apply to the alarm mechanism and no other action was taken. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="clock_alarm_reply.html"><strong>clock_alarm_reply<strong></a>. \ No newline at end of file +<h2>clock_reply_server</h2> +<hr> +<p> +<strong>Function</strong> - Handle kernel-generated alarm. +<h3>SYNOPSIS</h3> +<pre> +<strong>boolean_t clock_reply_server</strong> + <strong>(mach_msg_header_t</strong> <var>request_msg</var>, + <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>in_msg</var> +<dd> +[pointer to in structure] +The alarm message received from the kernel. +<p> +<dt> <var>out_msg</var> +<dd> +[out structure] +Not used. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>clock_reply_server</strong> function is the MIG generated server handling +function to handle messages from the kernel corresponding to +clock alarms. Such +messages are delivered to the alarm reply port named in a <strong>clock_alarm</strong> +call. The <strong>clock_reply_server</strong> function performs all necessary +argument handling for +this kernel message and calls the appropriate handling function. These functions +must be supplied by the caller. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The message was handled and the appropriate function was called. +<p> +<dt> <strong>FALSE</strong> +<dd> +The message did not apply to the alarm mechanism and no other action +was taken. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="clock_alarm_reply.html"><strong>clock_alarm_reply<strong></a>. diff --git a/osfmk/man/clock_set_attributes.html b/osfmk/man/clock_set_attributes.html index ecfec911b..6b2fb1d00 100755 --- a/osfmk/man/clock_set_attributes.html +++ b/osfmk/man/clock_set_attributes.html @@ -1 +1,68 @@ -<h2>clock_set_attributes</h2> <hr> <p> <strong>Function</strong> - Set a particular clock's attributes. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t clock_set_attributes</strong> <strong>(clock_ctrl_t</strong> <var>clock_control</var>, <strong>clock_flavor_t</strong> <var>flavor</var>, <strong>clock_attr_t</strong> <var>attribute</var>, <strong>clock_control</strong> <var>attribute_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>clock_control</var> <dd> [in clock-control send right] The control port for the clock. <p> <dt> <var>flavor</var> <dd> [in scalar] Type of information to be set. Defined values are: <dl> <p> <dt> <strong>CLOCK_ALARM_CURRES</strong> <dd> The resolution, in nanoseconds, at which clock alarm and sleep timers are currently serviced. Increasing the current resolution will have no impact on any pending clock alarms (i.e. they will go off as originally scheduled). Decreasing the current resolution will truncate any pending alarms to the granularity of the new current resolution. This value must be a multiple of the minimum resolution and not greater than the maximum resolution of the clock. </dl> <p> <dt> <var>attribute</var> <dd> [pointer to in scalar] New attribute. <p> <dt> <var>attribute_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>clock_set_attributes</strong> function sets attributes of a clock's operation. <h3>NOTES</h3> <p> The main reason a clock's current resolution would not always equal its minimum resolution is because the overhead of sustaining the minimum resolution, when it is not needed by any existing alarm service client, may be prohibitive for a given hardware platform and underlying clock device. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>, <a href="clock_set_time.html"><strong>clock_set_time</strong></a>, <a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>. \ No newline at end of file +<h2>clock_set_attributes</h2> +<hr> +<p> +<strong>Function</strong> - Set a particular clock's attributes. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t clock_set_attributes</strong> + <strong>(clock_ctrl_t</strong> <var>clock_control</var>, + <strong>clock_flavor_t</strong> <var>flavor</var>, + <strong>clock_attr_t</strong> <var>attribute</var>, + <strong>clock_control</strong> <var>attribute_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>clock_control</var> +<dd> +[in clock-control send right] +The control port for the clock. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +Type of information to be set. Defined values are: +<dl> +<p> +<dt> <strong>CLOCK_ALARM_CURRES</strong> +<dd> +The resolution, in nanoseconds, at which clock alarm and +sleep timers are currently serviced. Increasing the current +resolution will have no impact on any pending clock alarms (i.e. +they will go off as originally scheduled). Decreasing the +current resolution will truncate any pending alarms to the +granularity of the new current resolution. This value must be a +multiple of the minimum resolution and not greater than the +maximum resolution of the clock. +</dl> +<p> +<dt> <var>attribute</var> +<dd> +[pointer to in scalar] +New attribute. +<p> +<dt> <var>attribute_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>clock_set_attributes</strong> function sets attributes of +a clock's operation. +<h3>NOTES</h3> +<p> +The main reason a clock's current resolution would not always equal its +minimum resolution is because the overhead of sustaining the +minimum resolution, +when it is not needed by any existing alarm service client, may be prohibitive +for a given hardware platform and underlying clock device. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>, +<a href="clock_set_time.html"><strong>clock_set_time</strong></a>, +<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>. diff --git a/osfmk/man/clock_set_time.html b/osfmk/man/clock_set_time.html index 410a83251..50bfbcb14 100755 --- a/osfmk/man/clock_set_time.html +++ b/osfmk/man/clock_set_time.html @@ -1 +1,48 @@ -<h2>clock_set_time</h2> <hr> <p><strong>Function</strong> - Set the current time. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t clock_set_time</strong> <strong>(clock_ctrl_t</strong> <var>clock_control</var>, <strong>tvalspec_t</strong> <var>new_time</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>clock_control</var> <dd> [in clock-control send right] The control port for the clock. <p> <dt> <var>new_time</var> <dd> [in structure] New time </dl> <h3>DESCRIPTION</h3> <p> The <strong>clock_set_time</strong> function sets the time kept by a clock. Setting the clock time will cause all pending clock alarms and sleeps to be terminated with timestamps set to the current clock time just prior to the new time being set with a return code of <strong>KERN_ABORTED</strong>. <h3>CAUTIONS</h3> <p> The use of this function is \*Vstrongly discouraged\*O since it could affect the monotonically increasing nature of the clock. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>, <a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>, <a href="clock_get_time.html"><strong>clock_get_time</strong></a>, <a href="clock_alarm.html"><strong>clock_alarm</strong></a>, <a href="clock_sleep.html"><strong>clock_sleep</strong></a>. <p> Data Structures: <a href="tvalspec.html"><strong>tvalspec</strong></a>. \ No newline at end of file +<h2>clock_set_time</h2> +<hr> +<p><strong>Function</strong> - Set the current time. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t clock_set_time</strong> + <strong>(clock_ctrl_t</strong> <var>clock_control</var>, + <strong>tvalspec_t</strong> <var>new_time</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>clock_control</var> +<dd> +[in clock-control send right] +The control port for the clock. +<p> +<dt> <var>new_time</var> +<dd> +[in structure] +New time +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>clock_set_time</strong> function sets the time kept by a +clock. Setting the clock +time will cause all pending clock alarms and sleeps to be terminated with +timestamps set to the current clock time just prior to the new +time being set with a +return code of <strong>KERN_ABORTED</strong>. +<h3>CAUTIONS</h3> +<p> +The use of this function is \*Vstrongly discouraged\*O since it could affect the +monotonically increasing nature of the clock. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>, +<a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>, +<a href="clock_get_time.html"><strong>clock_get_time</strong></a>, +<a href="clock_alarm.html"><strong>clock_alarm</strong></a>, +<a href="clock_sleep.html"><strong>clock_sleep</strong></a>. +<p> +Data Structures: +<a href="tvalspec.html"><strong>tvalspec</strong></a>. diff --git a/osfmk/man/clock_sleep.html b/osfmk/man/clock_sleep.html index 4354f0a3c..681bc605d 100755 --- a/osfmk/man/clock_sleep.html +++ b/osfmk/man/clock_sleep.html @@ -1 +1,79 @@ -<h2>clock_sleep</h2> <hr> <p> <strong>System Trap</strong> - Sleep until a given time. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t clock_sleep</strong> <strong>(mach_port_t</strong> <var>clock_name</var>, <strong>sleep_type_t</strong> <var>sleep_type</var>, <strong>tvalspec_t</strong> <var>sleep_time</var>, <strong>clock_name</strong> <var>wake_time</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt><var>clock_name</var> <dd> [in clock-name send right] The name (or control) port for the clock. <p> <dt><var>sleep_type</var> <dd> [in scalar] How to interpret the sleep_time value: <dl> <p> <dt><strong>TIME_RELATIVE</strong> <dd> Interpret the sleep time as relative to the current time. <p> <dt><strong>TIME_ABSOLUTE</strong> <dd> Interpret the sleep time as an absolute time. </dl> <p> <dt><var>sleep_time</var> <dd> [in structure] The time when the sleep is to terminate. <p> <dt><var>wake_time</var> <dd> [out structure] The actual (absolute) time at which the sleep terminated. </dl> <h3>DESCRIPTION</h3> <p> The <strong>clock_sleep</strong> system trap delays the invoking thread until a specified time. This sleep may be aborted by <strong>thread_abort</strong>. Not all clocks provide this service but the REALTIME clock must. <p> If the specified time is in the past, the call returns immediately with the wake time being the current time. If the clock's time is changed (<strong>clock_set_time</strong>), the sleep will be interrupted. The thread will waken at the service time nearest the specified sleep time as governed by the current clock alarm resolution. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_FAILURE</strong> <dd> The clock does not support a sleep service. <p> <dt> <strong>KERN_ABORTED</strong> <dd> The sleep was interrupted by thread_abort or terminated via use of clock_set_time. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, <a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, <a href="clock_get_time.html"><strong>clock_get_time</strong></a>, <a href="clock_alarm.html"><strong>clock_alarm</strong></a>, <a href="clock_set_time.html"><strong>clock_set_time</strong></a>, <a href="thread_abort.html"><strong>thread_abort</strong></a>, <p> Data Structures: tvalspec. \ No newline at end of file +<h2>clock_sleep</h2> +<hr> +<p> +<strong>System Trap</strong> - Sleep until a given time. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t clock_sleep</strong> + <strong>(mach_port_t</strong> <var>clock_name</var>, + <strong>sleep_type_t</strong> <var>sleep_type</var>, + <strong>tvalspec_t</strong> <var>sleep_time</var>, + <strong>clock_name</strong> <var>wake_time</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt><var>clock_name</var> +<dd> +[in clock-name send right] The name (or control) port for the clock. +<p> +<dt><var>sleep_type</var> +<dd> +[in scalar] How to interpret the sleep_time value: + <dl> +<p> +<dt><strong>TIME_RELATIVE</strong> +<dd> +Interpret the sleep time as relative to the current time. +<p> +<dt><strong>TIME_ABSOLUTE</strong> +<dd> +Interpret the sleep time as an absolute time. + </dl> +<p> +<dt><var>sleep_time</var> +<dd> +[in structure] The time when the sleep is to terminate. +<p> +<dt><var>wake_time</var> +<dd> +[out structure] The actual (absolute) time at which the sleep terminated. +</dl> + +<h3>DESCRIPTION</h3> +<p> +The <strong>clock_sleep</strong> system trap delays the invoking +thread until a specified time. This sleep may be aborted by +<strong>thread_abort</strong>. Not all clocks provide this service +but the REALTIME clock must. +<p> +If the specified time is in the past, the call returns immediately +with the wake time being the current time. If the clock's time is +changed (<strong>clock_set_time</strong>), the sleep will be +interrupted. The thread will waken at the service time nearest the +specified sleep time as governed by the current clock alarm +resolution. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_FAILURE</strong> +<dd> +The clock does not support a sleep service. +<p> +<dt> <strong>KERN_ABORTED</strong> +<dd> +The sleep was interrupted by thread_abort or terminated via use of +clock_set_time. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>, +<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, +<a href="clock_get_time.html"><strong>clock_get_time</strong></a>, +<a href="clock_alarm.html"><strong>clock_alarm</strong></a>, +<a href="clock_set_time.html"><strong>clock_set_time</strong></a>, +<a href="thread_abort.html"><strong>thread_abort</strong></a>, +<p> +Data Structures: +tvalspec. diff --git a/osfmk/man/default_pager_add_segment.html b/osfmk/man/default_pager_add_segment.html index ad7028b1a..e214d0072 100755 --- a/osfmk/man/default_pager_add_segment.html +++ b/osfmk/man/default_pager_add_segment.html @@ -1 +1,80 @@ -<h2>default_pager_add_segment</h2> <hr> <p> <strong>Server Interface</strong> - Add additional backing storage for a default pager. <h3>SYNOPSIS</h3> <pre> <strong>#include< mach/default_pager_object.h></strong> <strong>kern_return_t default_pager_add_segment</strong> <strong>(mach_port_t</strong> <var>backing_store</var>, <strong>mach_port_t</strong> <var>device</var>, <strong>recnum_t</strong> <var>offset</var>, <strong>recnum_t</strong> <var>count</var>, <strong>int</strong> <var>record_size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>backing_store</var> <dd> [in backing store (receive) right] The backing store port. <p> <dt> <var>device</var> <dd> [in device port] The port for the device containing the backing storage partition. <p> <dt> <var>offset</var> <dd> [in scalar] The offset, in <var>record_size units</var>, to the beginning of the backing storage on the device. <p> <dt> <var>count</var> <dd> [in scalar] The number of <var>record_size</var> units in the partition/segment. <p> <dt> <var>record_size</var> <dd> [in scalar] The size, in bytes, of the storage device record. </dl> <h3>DESCRIPTION</h3> <p> The <strong>default_pager_add_segment</strong> function is called to add a partition to a default pager's backing storage (i.e. expand the amount of backing storage available to a memory manager). The kernel does not make this call itself (which is why it can be a synchronous call); this request is only issued by tasks holding the backing store port, created with <strong>default_pager_backing_store_create</strong>, for a default memory manager. The result is that the pager may use count records on device starting at offset for paging, and each record is record_size bytes in length (note that the device_* calls are, or can be, record oriented). <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_FAILURE</strong> <dd> The default pager does not support this operation. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The <var>backing_store</var> port does not represent a valid backing store or the specified segment overlaps an existing partition. <p> <dt> <strong>KERN_RESOURCE_SHORTAGE</strong> <dd> The default pager is unable to allocate internal resources to manage the new backing storage. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The operation was successful. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>, <a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>, <a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>. \ No newline at end of file +<h2>default_pager_add_segment</h2> +<hr> +<p> +<strong>Server Interface</strong> - Add additional backing storage for a default pager. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< mach/default_pager_object.h></strong> + +<strong>kern_return_t default_pager_add_segment</strong> + <strong>(mach_port_t</strong> <var>backing_store</var>, + <strong>mach_port_t</strong> <var>device</var>, + <strong>recnum_t</strong> <var>offset</var>, + <strong>recnum_t</strong> <var>count</var>, + <strong>int</strong> <var>record_size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>backing_store</var> +<dd> +[in backing store (receive) right] The backing store port. +<p> +<dt> <var>device</var> +<dd> +[in device port] The port for the device containing the backing storage +partition. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] The offset, in <var>record_size units</var>, to the beginning of the +backing storage on the device. +<p> +<dt> <var>count</var> +<dd> +[in scalar] The number of <var>record_size</var> units +in the partition/segment. +<p> +<dt> <var>record_size</var> +<dd> +[in scalar] The size, in bytes, of the storage device record. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>default_pager_add_segment</strong> function is called to add a partition to +a default pager's backing storage (i.e. expand the amount of backing +storage available to a memory manager). The kernel does not make +this call itself (which is why it can be a synchronous call); this +request is only issued by tasks holding the backing store port, +created with <strong>default_pager_backing_store_create</strong>, for a default memory +manager. +The result is that the pager may use count records on device starting +at offset for paging, and each record is record_size bytes in length +(note that the device_* calls are, or can be, record oriented). +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_FAILURE</strong> +<dd> +The default pager does not support this operation. +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The <var>backing_store</var> port does not represent a valid backing store or the +specified segment overlaps an existing partition. +<p> +<dt> <strong>KERN_RESOURCE_SHORTAGE</strong> +<dd> +The default pager is unable to allocate internal resources + to manage the new backing storage. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The operation was successful. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>, +<a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>, +<a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>. diff --git a/osfmk/man/default_pager_info.html b/osfmk/man/default_pager_info.html index 70f15d831..9a84b4b07 100755 --- a/osfmk/man/default_pager_info.html +++ b/osfmk/man/default_pager_info.html @@ -1 +1,58 @@ -<h2>default_pager_info</h2> <hr> <p> <strong>Server Interface</strong> - Furnish caller with information about the pager's paging partition. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t default_pager_info</strong> <strong>(mach_port_t</strong> <var>pager</var>, <strong>default_pager_info_t</strong> <var>info</var><strong>);</strong> <strong>kern_return_t seqnos_default_pager_info</strong> <strong>(mach_port_t</strong> <var>pager</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>default_pager_info_t</strong> <var>*info</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>pager</var> <dd> [in default-pager (receive) right] The default memory manager service port. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the pager port. <p> <dt> <var>info</var> <dd> [out structure] Total and free space consumption. </dl> <h3>DESCRIPTION</h3> <p> A <strong>default_pager_info</strong> function is called as the result of a message requesting that the default memory manager return information concerning the default pager's paging partitions. The kernel does not make this call itself (which is why it can be a synchronous call); this request is only issued by (privileged) tasks holding the default memory manager port. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="HD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>, <a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>, <a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>. <p> Data Structures: <a href="default_pager_info.html"><strong>default_pager_info</strong></a>. \ No newline at end of file +<h2>default_pager_info</h2> +<hr> +<p> +<strong>Server Interface</strong> - Furnish caller with information about the pager's paging partition. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t default_pager_info</strong> + <strong>(mach_port_t</strong> <var>pager</var>, + <strong>default_pager_info_t</strong> <var>info</var><strong>);</strong> + + +<strong>kern_return_t seqnos_default_pager_info</strong> + <strong>(mach_port_t</strong> <var>pager</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>default_pager_info_t</strong> <var>*info</var><strong>);</strong> + +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>pager</var> +<dd> +[in default-pager (receive) right] +The default memory manager service +port. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the pager +port. +<p> +<dt> <var>info</var> +<dd> +[out structure] +Total and free space consumption. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>default_pager_info</strong> function is called as the result +of a message requesting +that the default memory manager return information concerning the default +pager's paging partitions. The kernel does not make this call +itself (which is why it +can be a synchronous call); this request is only issued by (privileged) tasks +holding the default memory manager port. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="HD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>, +<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>, +<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>. +<p> +Data Structures: +<a href="default_pager_info.html"><strong>default_pager_info</strong></a>. diff --git a/osfmk/man/device_close.html b/osfmk/man/device_close.html index 570ae7111..14f4ed96e 100755 --- a/osfmk/man/device_close.html +++ b/osfmk/man/device_close.html @@ -1 +1,41 @@ -<h2>device_close</h2> <hr> <p> <strong>Function</strong> - De-establish a connection to a device. <h3>SYNOPSIS</h3> <pre> <strong>#include< device/device.h></strong> <strong>kern_return_t device_close</strong> <strong>(mach_port_t</strong> <var>device</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be closed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_close</strong> function destroys the associated device port. The open count for the named device is decremented. If this count reaches zero, the close operation of the device driver is invoked, closing the device. <h3>NOTES</h3> <p> <strong>device_close</strong> will destroy any mapped device windows obtained through this device port. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>D_NO_SUCH_DEVICE</strong> <dd> No device with that name, or the device is not operational. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_open.html"><strong>device_open</strong></a>. \ No newline at end of file +<h2>device_close</h2> +<hr> +<p> +<strong>Function</strong> - De-establish a connection to a device. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< device/device.h></strong> + +<strong>kern_return_t device_close</strong> + <strong>(mach_port_t</strong> <var>device</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] +A device port to the device to be closed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_close</strong> function destroys the associated device +port. The open count +for the named device is decremented. If this count reaches zero, the close +operation of the device driver is invoked, closing the device. +<h3>NOTES</h3> +<p> +<strong>device_close</strong> will destroy any mapped device windows +obtained through this +device port. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>D_NO_SUCH_DEVICE</strong> +<dd> +No device with that name, or the device is not operational. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_open.html"><strong>device_open</strong></a>. diff --git a/osfmk/man/device_get_status.html b/osfmk/man/device_get_status.html index 6d69a8ab4..e7b9bcf5a 100755 --- a/osfmk/man/device_get_status.html +++ b/osfmk/man/device_get_status.html @@ -1 +1,62 @@ -<h2>device_get_status</h2> <hr> <p> <strong>Function</strong> - Return the current device status. <h3>SYNOPSIS</h3> <pre> <strong>#include< device/device.h></strong> <strong>kern_return_t device_get_status</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>dev_flavor_t</strong> <var>flavor</var>, <strong>dev_status_t</strong> <var>status</var>, <strong>mach_msg_type_number_t</strong> <var>*status_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be interrogated. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of status information requested. <p> <dt> <var>status</var> <dd> [out array of natural-sized units] The returned device status. <p> <dt> <var>status_count</var> <dd> [pointer to in/out scalar] On input, the reserved size of <var>status</var>; on output, the size of the returned device status (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_get_status</strong> function returns status information pertaining to an open device. The possible values for <var>flavor</var> as well as the meaning of the returned status information is device dependent. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>D_DEVICE_DOWN</strong> <dd> Device has been shut down <p> <dt> <strong>D_NO_SUCH_DEVICE</strong> <dd> No device with that name, or the device is not operational. <p> <dt> <strong>D_OUT_OF_BAND</strong> <dd> Out-of-band condition occurred on device (such as typing \*L<Ctrl>-C\*O) </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_set_status.html"><strong>device_set_status</strong></a>. \ No newline at end of file +<h2>device_get_status</h2> +<hr> +<p> +<strong>Function</strong> - Return the current device status. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< device/device.h></strong> + +<strong>kern_return_t device_get_status</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>dev_flavor_t</strong> <var>flavor</var>, + <strong>dev_status_t</strong> <var>status</var>, + <strong>mach_msg_type_number_t</strong> <var>*status_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] +A device port to the device to be interrogated. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of status information requested. +<p> +<dt> <var>status</var> +<dd> +[out array of natural-sized units] +The returned device status. +<p> +<dt> <var>status_count</var> +<dd> +[pointer to in/out scalar] +On input, the reserved size of <var>status</var>; on +output, the size of the returned device status (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_get_status</strong> function returns status information +pertaining to an open device. The possible values for <var>flavor</var> as well +as the meaning of the returned status information is device dependent. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>D_DEVICE_DOWN</strong> +<dd> +Device has been shut down +<p> +<dt> <strong>D_NO_SUCH_DEVICE</strong> +<dd> +No device with that name, or the device is not operational. +<p> +<dt> <strong>D_OUT_OF_BAND</strong> +<dd> +Out-of-band condition occurred on device (such as typing \*L<Ctrl>-C\*O) +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_set_status.html"><strong>device_set_status</strong></a>. diff --git a/osfmk/man/device_map.html b/osfmk/man/device_map.html index ebd314198..26893f601 100755 --- a/osfmk/man/device_map.html +++ b/osfmk/man/device_map.html @@ -1 +1,106 @@ -<h2>device_map</h2> <hr> <p> <strong>Function</strong> - Establish the specified device's memory manager. <h3>SYNOPSIS</h3> <pre> <strong>#include< device/device.h></strong> <strong>kern_return_t device_map</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>vm_prot_t</strong> <var>prot</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>mach_port_t</strong> <var>mem_obj_t</var>, <strong>boolean_t</strong> <var>unmap</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be mapped. <p> <dt> <var>prot</var> <dd> [in scalar] Protection for the device memory. <p> <dt> <var>offset</var> <dd> [in scalar] 15~Offset in memory object. <p> <dt> <var>size</var> <dd> [in scalar] The size of the device memory object. <p> <dt> <var>pager</var> <dd> [out memory-object send right] The returned memory object representative port to a memory manager that represents the device. <p> <dt> <var>unmap</var> <dd> Unused. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_map</strong> function establishes a memory manager that presents a memory object representing a device. The resulting port is suitable for use as the memory manager port in a <strong>vm_map</strong> call. This call is device dependent. <h3>NOTES</h3> <p> Port rights are maintained as follows: <ul> <li> Memory object port: the device memory manager has all rights. <li> Memory cache control port: the device memory manager has only send rights. </ul> <p> Regardless of how the object is created, the control port is created by the kernel and passed through the memory management interface. <p> If the device port used is restricted to use by a single identity, the generated representative port will be likewise restricted. <h3>CAUTIONS</h3> <p> The device memory manager assumes that access to its memory objects will not be propagated to more that one host, and therefore provides no consistency guarantees beyond those made by the kernel. <p> In the event that more than one host attempts to use a device memory object, the device memory manager will only record the last set of port names. Currently, the device memory manager assumes that its clients adhere to the initialization and termination protocols in the memory management interface; otherwise, port rights or out-of-line memory from erroneous messages may be allowed to accumulate. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>D_DEVICE_DOWN</strong> <dd> Device has been shut down <p> <dt> <strong>D_NO_SUCH_DEVICE</strong> <dd> No device with that name, or the device is not operational. <p> <dt> <strong>D_READ_ONLY</strong> <dd> Data cannot be written to this device. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_map.html"><strong>vm_map</strong></a>. \ No newline at end of file +<h2>device_map</h2> +<hr> +<p> +<strong>Function</strong> - Establish the specified device's memory manager. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< device/device.h></strong> + +<strong>kern_return_t device_map</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>vm_prot_t</strong> <var>prot</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>mach_port_t</strong> <var>mem_obj_t</var>, + <strong>boolean_t</strong> <var>unmap</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] +A device port to the device to be mapped. +<p> +<dt> <var>prot</var> +<dd> +[in scalar] +Protection for the device memory. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +15~Offset in memory object. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The size of the device memory object. +<p> +<dt> <var>pager</var> +<dd> +[out memory-object send right] +The returned memory +object representative port to a memory manager that represents the +device. +<p> +<dt> <var>unmap</var> +<dd> +Unused. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_map</strong> function establishes a memory manager that presents a +memory object representing a device. The resulting port is suitable +for use as the +memory manager port in a <strong>vm_map</strong> call. This call is device dependent. +<h3>NOTES</h3> +<p> +Port rights are maintained as follows: +<ul> +<li> +Memory object port: the +device memory manager has all rights. +<li> +Memory cache control port: the device memory manager has only send rights. +</ul> +<p> +Regardless of how the object is created, the control port is created by +the kernel and passed through the memory management interface. +<p> +If the device port used is restricted to use by a single identity, +the generated +representative port will be likewise restricted. +<h3>CAUTIONS</h3> +<p> +The device memory manager assumes that access to its memory objects will not +be propagated to more that one host, and therefore provides no consistency +guarantees beyond those made by the kernel. +<p> +In the event that more than one host attempts to use a device +memory object, the +device memory manager will only record the last set of port names. Currently, +the device memory manager assumes that its clients adhere to +the initialization +and termination protocols in the memory management interface; otherwise, port +rights or out-of-line memory from erroneous messages may be allowed to +accumulate. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>D_DEVICE_DOWN</strong> +<dd> +Device has been shut down +<p> +<dt> <strong>D_NO_SUCH_DEVICE</strong> +<dd> +No device with that name, or the device is not operational. +<p> +<dt> <strong>D_READ_ONLY</strong> +<dd> +Data cannot be written to this device. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_map.html"><strong>vm_map</strong></a>. diff --git a/osfmk/man/device_open.html b/osfmk/man/device_open.html index 3fd4c350e..43bb366d7 100755 --- a/osfmk/man/device_open.html +++ b/osfmk/man/device_open.html @@ -1 +1,112 @@ -<h2>device_open</h2> <hr> <p> <strong>Function</strong> - Establish a connection to a device. <h3>SYNOPSIS</h3> <pre> <strong>#include<device/device.h></strong> <strong>kern_return_t device_open</strong> <strong>(mach_port_t</strong> <var>master_port</var>, <strong>mach_port_t</strong> <var>ledger</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>security_token_t</strong> <var>security_id</var>, <strong>dev_name_t</strong> <var>name</var>, <strong>mach_port_t</strong> <var>device</var><strong>);</strong> <strong>#include<device/device_request.h></strong> <strong>kern_return_t device_open_request</strong> <strong>(mach_port_t</strong> <var>master_port</var>, <strong>mach_port_t</strong> <var>reply_port</var>, <strong>mach_port_t</strong> <var>ledger</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>security_token_t</strong> <var>security_id</var>, <strong>dev_name_t</strong> <var>name</var><strong>);</strong> <strong>kern_return_t ds_device_open_reply</strong> <strong>(mach_port_t</strong> <var>reply_port</var>, <strong>kern_return_t</strong> <var>return_code</var>, <strong>mach_port_t</strong> <var>device</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>master_port</var> <dd> [in device-master send right] The master device port. This port is provided to the bootstrap task. <p> <dt> <var>reply_port</var> <dd> [in reply receive (to be converted to send-once) right] The port to which a reply is to be sent when the device is open. <p> <dt> <var>ledger</var> <dd> [pointer to a ledger send right] Resource ledger from which the device will draw its resources. <p> <dt> <var>mode</var> <dd> [in scalar] Opening mode. This is the bit-wise <strong>OR</strong> of the following values: <dl> <p> <dt> <strong>D_READ</strong> <dd> Read access <p> <dt> <strong>D_WRITE</strong> <dd> Write access <p> <dt> <strong>D_NODELAY</strong> <dd> Do not delay on open </dl> <p> <dt> <var>security_id</var> <dd> [in scalar] The security ID that tasks attempting to use this device port must have. A zero value indicates all identities. <p> <dt> <var>name</var> <dd> [pointer to in array of <var>char</var>] Name of the device to open. <p> <dt> <var>return_code</var> <dd> [in scalar] Status of the open. <p> <dt> <var>device</var> <dd> [out device send right, in for asynchronous form] The returned device port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_open</strong> function opens a device object. The open operation of the device is invoked, if the device is not already open. The open count for the device is incremented. Each open for a device returns a port, the allowed operations upon which being governed by <var>mode</var>. The port is not distinct. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_close.html"><strong>device_close</strong></a>, <a href="device_reply_server.html"><strong>device_reply_server</strong></a>. \ No newline at end of file +<h2>device_open</h2> +<hr> +<p> +<strong>Function</strong> - Establish a connection to a device. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<device/device.h></strong> + +<strong>kern_return_t device_open</strong> + <strong>(mach_port_t</strong> <var>master_port</var>, + <strong>mach_port_t</strong> <var>ledger</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>security_token_t</strong> <var>security_id</var>, + <strong>dev_name_t</strong> <var>name</var>, + <strong>mach_port_t</strong> <var>device</var><strong>);</strong> + + +<strong>#include<device/device_request.h></strong> + +<strong>kern_return_t device_open_request</strong> + <strong>(mach_port_t</strong> <var>master_port</var>, + <strong>mach_port_t</strong> <var>reply_port</var>, + <strong>mach_port_t</strong> <var>ledger</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>security_token_t</strong> <var>security_id</var>, + <strong>dev_name_t</strong> <var>name</var><strong>);</strong> + + +<strong>kern_return_t ds_device_open_reply</strong> + <strong>(mach_port_t</strong> <var>reply_port</var>, + <strong>kern_return_t</strong> <var>return_code</var>, + <strong>mach_port_t</strong> <var>device</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>master_port</var> +<dd> +[in device-master send right] +The master device port. This port is +provided to the bootstrap task. +<p> +<dt> <var>reply_port</var> +<dd> +[in reply receive (to be converted to send-once) right] +The port to +which a reply is to be sent when the device is open. +<p> +<dt> <var>ledger</var> +<dd> +[pointer to a ledger send right] +Resource ledger from which the device will draw its resources. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] +Opening mode. This is the bit-wise <strong>OR</strong> of the following +values: +<dl> +<p> +<dt> <strong>D_READ</strong> +<dd> +Read access +<p> +<dt> <strong>D_WRITE</strong> +<dd> +Write access +<p> +<dt> <strong>D_NODELAY</strong> +<dd> +Do not delay on open +</dl> +<p> +<dt> <var>security_id</var> +<dd> +[in scalar] +The security ID that tasks attempting to use this device port +must have. A zero value indicates all identities. +<p> +<dt> <var>name</var> +<dd> +[pointer to in array of <var>char</var>] +Name of the device to open. +<p> +<dt> <var>return_code</var> +<dd> +[in scalar] +Status of the open. +<p> +<dt> <var>device</var> +<dd> +[out device send right, in for asynchronous form] +The returned device +port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_open</strong> function opens a device object. The +open operation of the +device is invoked, if the device is not already open. The open +count for the device +is incremented. Each open for a device returns a port, the allowed +operations upon which being governed by <var>mode</var>. The port is not +distinct. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_close.html"><strong>device_close</strong></a>, +<a href="device_reply_server.html"><strong>device_reply_server</strong></a>. diff --git a/osfmk/man/device_read.html b/osfmk/man/device_read.html index 56d3b776e..3b91f97f4 100755 --- a/osfmk/man/device_read.html +++ b/osfmk/man/device_read.html @@ -1 +1,100 @@ -<h2>device_read</h2> <hr> <p> <strong>Function</strong> - Read a sequence of bytes from a specific device. <h3>SYNOPSIS</h3> <pre> <strong>#include<device/device.h></strong> <strong>kern_return_t device_read</strong> <strong>(device_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>reply_port</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var>, <strong>io_buf_ptr_t</strong> <var>io_buf_ptr_t</var>, <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong> <strong>#include<device/device_request.h></strong> <strong>kern_return_t device_read_request</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>reply_port</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> <strong>kern_return_t ds_device_read_reply</strong> <strong>(mach_port_t</strong> <var>reply_port</var>, <strong>kern_return_t</strong> <var>return_code</var>, <strong>io_buf_ptr_t</strong> <var>data</var>, <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be read. <p> <dt> <var>reply_port</var> <dd> [in reply receive (to be converted to send-once) right] The port to which the reply message is to be sent. <p> <dt> <var>mode</var> <dd> [in scalar] I/O mode value. Meaningful options are: <dl> <p> <dt> <strong>D_NOWAIT</strong> <dd> Do not wait if data is unavailable. </dl> <p> <dt> <var>recnum</var> <dd> [in scalar] Record number to be read. <p> <dt> <var>bytes_wanted</var> <dd> [in scalar] Size of data transfer. <p> <dt> <var>return_code</var> <dd> [in scalar] The return status code from the read. <p> <dt> <var>data</var> <dd> [out pointer to dynamic array of bytes, in for asynchronous form] Returned data bytes. <p> <dt> <var>data_count</var> <dd> [out scalar, in for asynchronous form] Number of returned data bytes. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_read</strong> function reads a sequence of bytes from a device object. The meaning of <var>recnum</var> as well as the specific operation performed is device dependent. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_read_inband.html"><strong>device_read_inband</strong></a>, <a href="device_read_overwrite.html"><strong>device_read_overwrite</strong></a>, <a href="device_reply_server.html"><strong>device_reply_server</strong></a>. \ No newline at end of file +<h2>device_read</h2> +<hr> +<p> +<strong>Function</strong> - Read a sequence of bytes from a specific device. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<device/device.h></strong> + +<strong>kern_return_t device_read</strong> + <strong>(device_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>reply_port</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var>, + <strong>io_buf_ptr_t</strong> <var>io_buf_ptr_t</var>, + <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong> + + +<strong>#include<device/device_request.h></strong> + +<strong>kern_return_t device_read_request</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>reply_port</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> + + + +<strong>kern_return_t ds_device_read_reply</strong> + <strong>(mach_port_t</strong> <var>reply_port</var>, + <strong>kern_return_t</strong> <var>return_code</var>, + <strong>io_buf_ptr_t</strong> <var>data</var>, + <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] +A device port to the device to be read. +<p> +<dt> <var>reply_port</var> +<dd> +[in reply receive (to be converted to send-once) right] +The port to +which the reply message is to be sent. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] +I/O mode value. Meaningful options are: +<dl> +<p> +<dt> <strong>D_NOWAIT</strong> +<dd> +Do not wait if data is unavailable. +</dl> +<p> +<dt> <var>recnum</var> +<dd> +[in scalar] +Record number to be read. +<p> +<dt> <var>bytes_wanted</var> +<dd> +[in scalar] +Size of data transfer. +<p> +<dt> <var>return_code</var> +<dd> +[in scalar] +The return status code from the read. +<p> +<dt> <var>data</var> +<dd> +[out pointer to dynamic array of bytes, in for asynchronous form] +Returned data bytes. +<p> +<dt> <var>data_count</var> +<dd> +[out scalar, in for asynchronous form] +Number of returned data bytes. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_read</strong> function reads a sequence of bytes +from a device object. The +meaning of <var>recnum</var> as well as the specific operation performed is device +dependent. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_read_inband.html"><strong>device_read_inband</strong></a>, +<a href="device_read_overwrite.html"><strong>device_read_overwrite</strong></a>, +<a href="device_reply_server.html"><strong>device_reply_server</strong></a>. diff --git a/osfmk/man/device_read_async.html b/osfmk/man/device_read_async.html index bef750fab..279773229 100755 --- a/osfmk/man/device_read_async.html +++ b/osfmk/man/device_read_async.html @@ -1 +1,67 @@ -<h2>device_read_async</h2> <hr> <p> <strong>System Trap</strong> - Read a sequence of bytes from a device object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t device_read_async</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>queue</var>, <strong>mach_port_t</strong> <var>request_id</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be read. <p> <dt> <var>queue</var> <dd> [in io_done queue send right] The port returned from io_done_queue_create. <p> <dt> <var>request_id</var> <dd> [in send right] An unique request identifier that will be passed back as part of the io_done_result structure. <p> <dt> <var>mode</var> <dd> [in scalar] I/O mode value. Meaningful options are: <p> <dl> <dt> <strong>D_NOWAIT</strong> <dd> Do not wait if data is unavailable. </dl> <p> <dt> <var>recnum</var> <dd> [in scalar] Record number to be read. <p> <dt> <var>bytes_wanted</var> <dd> [in scalar] Size of data transfer. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_read_async</strong> interface enqueues a read operation for a sequence of bytes from a device object. The meaning of recnum as well as the specific operation performed is device dependent. <h3>RETURN VALUES</h3> <dl> <strong>device_read_async</strong> returns only invalid parameter errors. <dd> </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, <a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, <a href="device_write_async.html"><strong>device_write_async</strong></a>, <a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>, <a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>. \ No newline at end of file +<h2>device_read_async</h2> +<hr> +<p> +<strong>System Trap</strong> - Read a sequence of bytes from a device object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t device_read_async</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>queue</var>, + <strong>mach_port_t</strong> <var>request_id</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] A device port to the device to be read. +<p> +<dt> <var>queue</var> +<dd> +[in io_done queue send right] The port returned from +io_done_queue_create. +<p> +<dt> <var>request_id</var> +<dd> +[in send right] An unique request identifier that will be passed back as +part of the io_done_result structure. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] I/O mode value. Meaningful options are: +<p> + <dl> +<dt> <strong>D_NOWAIT</strong> +<dd> +Do not wait if data is unavailable. + </dl> +<p> +<dt> <var>recnum</var> +<dd> +[in scalar] Record number to be read. +<p> +<dt> <var>bytes_wanted</var> +<dd> +[in scalar] Size of data transfer. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_read_async</strong> interface enqueues a read operation for a +sequence of bytes from a device object. The meaning of recnum as well +as the specific operation performed is device dependent. +<h3>RETURN VALUES</h3> +<dl> +<strong>device_read_async</strong> returns only invalid parameter errors. +<dd> +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, +<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, +<a href="device_write_async.html"><strong>device_write_async</strong></a>, +<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>, +<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>. diff --git a/osfmk/man/device_read_async_inband.html b/osfmk/man/device_read_async_inband.html index 13b556b6b..9d26fec61 100755 --- a/osfmk/man/device_read_async_inband.html +++ b/osfmk/man/device_read_async_inband.html @@ -1 +1,68 @@ -<h2>device_read_async_inband</h2> <hr> <p> <strong>System Trap</strong> - Read a sequence of bytes "inband" from a device object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t device_read_async_inband</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>queue</var>, <strong>mach_port_t</strong> <var>request_id</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be read. <p> <dt> <var>queue</var> <dd> [in io_done queue send right] The port returned from <strong>io_done_queue_create</strong>. <p> <dt> <var>request_id</var> <dd> [in send right] An unique request identifier that will be passed back as part of the io_done_result structure. <p> <dt> <var>mode</var> <dd> [in scalar] I/O mode value. Meaningful options are: <p> <dl> <dt> <strong>D_NOWAIT</strong> <dd> Do not wait if data is unavailable. </dl> <p> <dt> <var>recnum</var> <dd> [in scalar] Record number to be read. <p> <dt> <var>bytes_wanted</var> <dd> [in scalar] Size of data transfer. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_read_async_inband</strong> function enqueues a read operation for a sequence of bytes from a device object. The meaning of <var>recnum</var> as well as the specific operation performed is device dependent. This call differs from <strong>device_read_async</strong> in that the returned bytes are returned "inband" in the completion IPC message (in <strong>io_done_result.qd_inline</strong>). <h3>RETURN VALUES</h3> <p> <strong>device_read_async_inband</strong> returns only invalid parameter errors. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_read_async.html"><strong>device_read_async</strong></a>, <a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, <a href="device_write_async.html"><strong>device_write_async</strong></a>, <a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>, <a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>. \ No newline at end of file +<h2>device_read_async_inband</h2> +<hr> +<p> +<strong>System Trap</strong> - Read a sequence of bytes "inband" from a device object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t device_read_async_inband</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>queue</var>, + <strong>mach_port_t</strong> <var>request_id</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] A device port to the device to be read. +<p> +<dt> <var>queue</var> +<dd> +[in io_done queue send right] The port returned from +<strong>io_done_queue_create</strong>. +<p> +<dt> <var>request_id</var> +<dd> +[in send right] An unique request identifier that will be passed back as +part of the io_done_result structure. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] I/O mode value. Meaningful options are: +<p> + <dl> +<dt> <strong>D_NOWAIT</strong> +<dd> +Do not wait if data is unavailable. + </dl> +<p> +<dt> <var>recnum</var> +<dd> +[in scalar] Record number to be read. +<p> +<dt> <var>bytes_wanted</var> +<dd> +[in scalar] Size of data transfer. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_read_async_inband</strong> function enqueues a read operation for a +sequence of bytes from a device object. The meaning of <var>recnum</var> as +well as the specific operation performed is device dependent. This +call differs from <strong>device_read_async</strong> in that the returned bytes are +returned "inband" in the completion IPC message (in +<strong>io_done_result.qd_inline</strong>). +<h3>RETURN VALUES</h3> +<p> +<strong>device_read_async_inband</strong> returns only invalid parameter errors. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_read_async.html"><strong>device_read_async</strong></a>, +<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, +<a href="device_write_async.html"><strong>device_write_async</strong></a>, +<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>, +<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>. diff --git a/osfmk/man/device_read_inband.html b/osfmk/man/device_read_inband.html index d7467eef3..8aaa4f5eb 100755 --- a/osfmk/man/device_read_inband.html +++ b/osfmk/man/device_read_inband.html @@ -1 +1,100 @@ -<h2>device_read_inband</h2> <hr> <p> <strong>Function</strong> - Read a sequence of bytes "inband" from a device object. <h3>SYNOPSIS</h3> <pre> <strong>#include<device/device.h></strong> <strong>kern_return_t device_read_inband</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var>, <strong>io_buf_ptr_inband_t</strong> <var>data</var>, <strong>mach_msg_type_number_t</strong> <var>*data_count</var><strong>);</strong> <strong>#include<device/device_request.h></strong> <strong>kern_return_t device_read_request_inband</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>reply_port</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> <strong>kern_return_t ds_device_read_reply_inband</strong> <strong>(mach_port_t</strong> <var>reply_port</var>, <strong>kern_return_t</strong> <var>return_code</var>, <strong>io_buf_ptr_inband_t</strong> <var>data</var>, <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be read. <p> <dt> <var>reply_port</var> <dd> [in reply receive (to be converted to send-once) right] The port to which the reply message is to be sent. <p> <dt> <var>mode</var> <dd> [in scalar] I/O mode value. Meaningful options are: <dl> <p> <dt> <strong>D_NOWAIT</strong> <dd> Do not wait if data is unavailable. </dl> <p> <dt> <var>recnum</var> <dd> [in scalar] Record number to be read. <p> <dt> <var>bytes_wanted</var> <dd> [in scalar] Size of data transfer. <p> <dt> <var>return_code</var> <dd> [in scalar] The return status code from the read. <p> <dt> <var>data</var> <dd> [out array of bytes, in for asynchronous form] Returned data bytes. <p> <dt> <var>data_count</var> <dd> [out scalar, in for asynchronous form] Number of returned data bytes. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_read_inband</strong> function reads a sequence of bytes from a device object. The meaning of <var>recnum</var> as well as the specific operation performed is device dependent. This call differs from <strong>device_read</strong> in that the returned bytes are returned "inband" in the reply IPC message. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_read.html"><strong>device_read</strong></a>, <a href="device_read_overwrite.html"><strong>device_read_overwrite</strong></a>, <a href="device_reply_server.html"><strong>device_reply_server</strong></a>. \ No newline at end of file +<h2>device_read_inband</h2> +<hr> +<p> +<strong>Function</strong> - Read a sequence of bytes "inband" from a device object. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<device/device.h></strong> + +<strong>kern_return_t device_read_inband</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var>, + <strong>io_buf_ptr_inband_t</strong> <var>data</var>, + <strong>mach_msg_type_number_t</strong> <var>*data_count</var><strong>);</strong> + + +<strong>#include<device/device_request.h></strong> + +<strong>kern_return_t device_read_request_inband</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>reply_port</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> + + +<strong>kern_return_t ds_device_read_reply_inband</strong> + <strong>(mach_port_t</strong> <var>reply_port</var>, + <strong>kern_return_t</strong> <var>return_code</var>, + <strong>io_buf_ptr_inband_t</strong> <var>data</var>, + <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] +A device port to the device to be read. +<p> +<dt> <var>reply_port</var> +<dd> +[in reply receive (to be converted to send-once) right] +The port to +which the reply message is to be sent. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] +I/O mode value. Meaningful options are: +<dl> +<p> +<dt> <strong>D_NOWAIT</strong> +<dd> +Do not wait if data is unavailable. +</dl> +<p> +<dt> <var>recnum</var> +<dd> +[in scalar] +Record number to be read. +<p> +<dt> <var>bytes_wanted</var> +<dd> +[in scalar] +Size of data transfer. +<p> +<dt> <var>return_code</var> +<dd> +[in scalar] +The return status code from the read. +<p> +<dt> <var>data</var> +<dd> +[out array of bytes, in for asynchronous form] +Returned data bytes. +<p> +<dt> <var>data_count</var> +<dd> +[out scalar, in for asynchronous form] +Number of returned data bytes. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_read_inband</strong> function reads a sequence of bytes +from a device object. The +meaning of <var>recnum</var> as well as the specific operation performed is device +dependent. This call differs from <strong>device_read</strong> in that +the returned bytes are returned +"inband" in the reply IPC message. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_read.html"><strong>device_read</strong></a>, +<a href="device_read_overwrite.html"><strong>device_read_overwrite</strong></a>, +<a href="device_reply_server.html"><strong>device_reply_server</strong></a>. diff --git a/osfmk/man/device_read_overwrite.html b/osfmk/man/device_read_overwrite.html index 8551c9144..6d81e4ca0 100755 --- a/osfmk/man/device_read_overwrite.html +++ b/osfmk/man/device_read_overwrite.html @@ -1 +1,101 @@ -<h2>device_read_overwrite</h2> <hr> <p><strong>System Trap</strong> -- Read a sequence of bytes from a specific device into my address space. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t device_read_overwrite</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var>, <strong>io_buf_pointer_t</strong> <var>data</var>, <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> <strong>kern_return_t device_read_overwrite_request</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>reply_port</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var>, <strong>io_buf_pointer_t</strong> <var>data</var><strong>);</strong> <strong>kern_return_t ds_device_read_reply_overwrite</strong> <strong>(mach_port_t</strong> <var>reply_port</var>, <strong>kern_return_t</strong> <var>return_code</var>, <strong>io_buf_len_t</strong> <var>data_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be read. <p> <dt> <var>reply_port</var> <dd> [in reply receive (to be converted to send-once) right] The port to which the reply message is to be sent. <p> <dt> <var>mode</var> <dd> [in scalar] I/O mode value. Meaningful options are: <dl> <p> <dt> <strong>D_NOWAIT</strong> <dd> Do not wait if data is unavailable. </dl> <p> <dt> <var>recnum</var> <dd> [in scalar] Record number to be read. <p> <dt> <var>bytes_wanted</var> <dd> [in scalar] Size of data transfer. <p> <dt> <var>return_code</var> <dd> [in scalar] The return status code from the read. <p> <dt> <var>data</var> <dd> [pointer to in array of bytes] Data buffer to be overwritten. <p> <dt> <var>data_count</var> <dd> [out scalar, in for asynchronous form] Number of returned data bytes. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_read_overwrite</strong> system trap reads a sequence of bytes from a device object directly into the caller's address space. The meaning of <var>recnum</var> as well as the specific operation performed is device dependent. <h3>NOTES</h3> <p> The <strong>device_read_overwrite_request</strong> and <strong>device_read_reply_overwrite</strong> calls may be removed from the interface in favor of new asynchronous support. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_read.html"><strong>device_read</strong></a>, <a href="device_read_inband.html"><strong>device_read_inband</strong></a>, <a href="device_reply_server.html"><strong>device_reply_server</strong></a>. \ No newline at end of file +<h2>device_read_overwrite</h2> +<hr> +<p><strong>System Trap</strong> -- Read a sequence of bytes from a specific device into my address space. +<h3>SYNOPSIS</h3> +<pre> + +<strong>kern_return_t device_read_overwrite</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var>, + <strong>io_buf_pointer_t</strong> <var>data</var>, + <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> + + + +<strong>kern_return_t device_read_overwrite_request</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>reply_port</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var>, + <strong>io_buf_pointer_t</strong> <var>data</var><strong>);</strong> + + + +<strong>kern_return_t ds_device_read_reply_overwrite</strong> + <strong>(mach_port_t</strong> <var>reply_port</var>, + <strong>kern_return_t</strong> <var>return_code</var>, + <strong>io_buf_len_t</strong> <var>data_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] +A device port to the device to be read. +<p> +<dt> <var>reply_port</var> +<dd> +[in reply receive (to be converted to send-once) right] +The port to +which the reply message is to be sent. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] +I/O mode value. Meaningful options are: +<dl> +<p> +<dt> <strong>D_NOWAIT</strong> +<dd> +Do not wait if data is unavailable. +</dl> +<p> +<dt> <var>recnum</var> +<dd> +[in scalar] +Record number to be read. +<p> +<dt> <var>bytes_wanted</var> +<dd> +[in scalar] +Size of data transfer. +<p> +<dt> <var>return_code</var> +<dd> +[in scalar] +The return status code from the read. +<p> +<dt> <var>data</var> +<dd> +[pointer to in array of bytes] +Data buffer to be overwritten. +<p> +<dt> <var>data_count</var> +<dd> +[out scalar, in for asynchronous form] +Number of returned data bytes. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_read_overwrite</strong> system trap reads a sequence +of bytes from a +device object directly into the caller's address space. The +meaning of <var>recnum</var> as +well as the specific operation performed is device dependent. +<h3>NOTES</h3> +<p> +The <strong>device_read_overwrite_request</strong> and <strong>device_read_reply_overwrite</strong> +calls may be removed from the interface in favor of new asynchronous support. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_read.html"><strong>device_read</strong></a>, +<a href="device_read_inband.html"><strong>device_read_inband</strong></a>, +<a href="device_reply_server.html"><strong>device_reply_server</strong></a>. diff --git a/osfmk/man/device_reply_server.html b/osfmk/man/device_reply_server.html index 344b45bc2..a992ff5fd 100755 --- a/osfmk/man/device_reply_server.html +++ b/osfmk/man/device_reply_server.html @@ -1 +1,58 @@ -<h2>device_reply_server</h2> <hr> <p> <strong>Function</strong> - Handle incoming data from kernel device driver. <h3>SYNOPSIS</h3> <pre> <strong>boolean_t device_reply_server</strong> <strong>(mach_msg_header_t</strong> <var>request_msg</var>, <strong>mach_msg_header_t</strong> <var>reply_msg</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>request_msg</var> <dd> [pointer to in structure] The device driver message received from the kernel. <p> <dt> <var>reply_msg</var> <dd> [out structure] A reply message. No messages from a device driver expect a direct reply, so this field is not used. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_reply_server</strong> function is the MIG generated server handling function to handle messages from kernel device drivers. Such messages were sent in response to the various <strong>device_</strong>...<strong>_request</strong>... calls. It is assumed when using those calls that some task is listening for reply messages on the port named as a reply port to those calls. The <strong>device_reply_server</strong> function performs all necessary argument handling for a kernel message and calls one of the device server functions to interpret the message. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>TRUE</strong> <dd> The message was handled and the appropriate function was called. <p> <dt> <strong>FALSE</strong> <dd> The message did not apply to this device handler interface and no other action was taken. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_open.html"><strong>ds_device_open_reply<strong></a>, <a href="device_write.html"><strong>ds_device_write_reply<strong></a>, <a href="device_write_inband.html"><strong>ds_device_write_reply_inband<strong></a>, <a href="device_read.html"><strong>ds_device_read_reply<strong></a>, <a href="device_read_inband.html"><strong>ds_device_read_reply_inband<strong></a>, <a href="device_read_overwrite.html"><strong>ds_device_read_reply_overwrite<strong></a>. \ No newline at end of file +<h2>device_reply_server</h2> +<hr> +<p> +<strong>Function</strong> - Handle incoming data from kernel device driver. +<h3>SYNOPSIS</h3> +<pre> +<strong>boolean_t device_reply_server</strong> + <strong>(mach_msg_header_t</strong> <var>request_msg</var>, + <strong>mach_msg_header_t</strong> <var>reply_msg</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>request_msg</var> +<dd> +[pointer to in structure] +The device driver message received from the +kernel. +<p> +<dt> <var>reply_msg</var> +<dd> +[out structure] +A reply message. No messages from a device driver +expect a direct reply, so this field is not used. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_reply_server</strong> function is the MIG generated server handling +function to handle messages from kernel device drivers. Such +messages were sent in response to the various +<strong>device_</strong>...<strong>_request</strong>... +calls. It is assumed when using +those calls that some task is listening for reply messages on the port named as a +reply port to those calls. The <strong>device_reply_server</strong> +function performs all +necessary argument handling for a kernel message and calls one +of the device server functions to interpret the message. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The message was handled and the appropriate function was called. +<p> +<dt> <strong>FALSE</strong> +<dd> +The message did not apply to this device handler interface and no other +action was taken. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_open.html"><strong>ds_device_open_reply<strong></a>, +<a href="device_write.html"><strong>ds_device_write_reply<strong></a>, +<a href="device_write_inband.html"><strong>ds_device_write_reply_inband<strong></a>, +<a href="device_read.html"><strong>ds_device_read_reply<strong></a>, +<a href="device_read_inband.html"><strong>ds_device_read_reply_inband<strong></a>, +<a href="device_read_overwrite.html"><strong>ds_device_read_reply_overwrite<strong></a>. diff --git a/osfmk/man/device_set_filter.html b/osfmk/man/device_set_filter.html index 1f3ff8245..c6ee08a39 100755 --- a/osfmk/man/device_set_filter.html +++ b/osfmk/man/device_set_filter.html @@ -1 +1,194 @@ -<h2>device_set_filter</h2> <hr> <p> <strong>Function</strong> - Name an input filter for a device. <h3>SYNOPSIS</h3> <pre> <strong>#include< device/device.h></strong> <strong>#include< device/net_status.h></strong> <strong>kern_return_t device_set_filter</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>receive_port</var>, <strong>mach_msg_type_name_t</strong> <var>receive_port_type</var>, <strong>int</strong> <var>priority</var>, <strong>filter_array_t</strong> <var>filter</var>, <strong>mach_msg_type_number_t</strong> <var>filter_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port <p> <dt> <var>receive_port</var> <dd> [in filter send or receive (to be converted to send) right] The port to receive the input data that is selected by the filter. <p> <dt> <var>receive_port_type</var> <dd> [in scalar] IPC type of the send right provided to the device; either <strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>, or <strong>MACH_MSG_TYPE_COPY_SEND</strong>. <p> <dt> <var>priority</var> <dd> [in scalar] Used to order multiple receivers in an implementation dependent way. <p> <dt> <var>filter</var> <dd> [pointer to in array of <var>filter_t</var>] The address of an array of filter values. <p> <dt> <var>filter_count</var> <dd> [in scalar] The size of the <var>filter</var> array (in 16-bit values). </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_set_filter</strong> function provides a means by which selected data appearing at a device interface can be selected and routed to a port. This service is provided in support of network devices. <p> The filter command list consists of an array of up to <strong>NET_MAX_FILTER</strong> (16-bit) values to be applied to incoming data "messages" to determine if that data should be given to a particular input filter. <p> Each filter command list specifies a sequence of actions which leave a boolean value on the top of an internal stack. Each 16-bit value of the command list specifies a data (push) operation (high order <strong>NETF_NBPO</strong> bits) as well as a binary operator (low order <strong>NETF_NBPA</strong> bits). <p> The value to be pushed onto the stack is chosen as follows: <dl> <dt> <strong>NETF_PUSHLIT</strong> <dd> Use the next 16-bit value of the filter as the value. <dt> <strong>NETF_PUSHZERO</strong> <dd> Use 0 as the value. <dt> <strong>NETF_PUSHWORD+</strong><var>N</var> <dd> Use 16-bit value <var>N</var> of the "data" portion of the message as the value. <dt> <strong>NETF_PUSHHDR+</strong><var>N</var> <dd> Use 16-bit value <var>N</var> of the "header" portion of the message as the value. <dt> <strong>NETF_PUSHIND</strong> <dd> Pops the top 32-bit value from the stack and then uses it to index the 16-bit value of the "data" portion of the message to be used as the value. <dt> <strong>NETF_PUSHHDRIND</strong> <dd> Pops the top 32-bit value from the stack and then uses it to index the 16-bit value of the "header" portion of the message to be used as the value. <dt> <strong>NETF_PUSHSTK+</strong><var>N</var> <dd> Use 32-bit value <var>N</var> of the stack (where the top of stack is value 0) as the value. <dt> <strong>NETF_NOPUSH</strong> <dd> Don't push a value. </dl> The unsigned value so chosen is promoted to a 32-bit value before being pushed. <p> Once a value is pushed (except for the case of <strong>NETF_NOPUSH</strong>), the top two 32-bit values of the stack are popped and a binary operator applied to them (with the old top of stack as the second operand). The result of the operator is pushed on the stack. These operators are: <dl> <dt> <strong>NETF_NOP</strong> <dd> Don't pop off any values and do no operation. <dt> <strong>NETF_EQ</strong> <dd> Perform an equal comparison. <dt> <strong>NETF_LT</strong> <dd> Perform a less than comparison. <dt> <strong>NETF_LE</strong> <dd> Perform a less than or equal comparison. <dt> <strong>NETF_GT</strong> <dd> Perform a greater than comparison. <dt> <strong>NETF_GE</strong> <dd> Perform a greater than or equal comparison. <dt> <strong>NETF_AND</strong> <dd> Perform a bit-wise boolean AND operation. <dt> <strong>NETF_OR</strong> <dd> Perform a bit-wise boolean inclusive OR operation. <dt> <strong>NETF_XOR</strong> <dd> Perform a bit-wise boolean exclusive OR operation. <dt> <strong>NETF_NEQ</strong> <dd> Perform a not equal comparison. <dt> <strong>NETF_LSH</strong> <dd> Perform a left shift operation. <dt> <strong>NETF_RSH</strong> <dd> Perform a right shift operation. <dt> <strong>NETF_ADD</strong> <dd> Perform an addition. <dt> <strong>NETF_SUB</strong> <dd> Perform a subtraction. <dt> <strong>NETF_COR</strong> <dd> Perform an equal comparison. If the comparison is <strong>TRUE</strong>, terminate the filter list. Otherwise, pop the result of the comparison off the stack. <dt> <strong>NETF_CAND</strong> <dd> Perform an equal comparison. If the comparison is <strong>FALSE</strong>, terminate the filter list. Otherwise, pop the result of the comparison off the stack. <dt> <strong>NETF_CNOR</strong> <dd> Perform a not equal comparison. If the comparison is <strong>FALSE</strong>, terminate the filter list. Otherwise, pop the result of the comparison off the stack. <dt> <strong>NETF_CNAND</strong> <dd> Perform a not equal comparison. If the comparison is <strong>TRUE</strong>, terminate the filter list. Otherwise, pop the result of the comparison off the stack. </dl> The scan of the filter list terminates when the filter list is emptied, or a <strong>NETF_C</strong> operation terminates the list. At this time, if the final value of the top of the stack is <strong>TRUE</strong>, then the message is accepted for the filter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>D_DEVICE_DOWN</strong> <dd> Device has been shut down <p> <dt> <strong>D_INVALID_OPERATION</strong> <dd> No filter port was supplied. <p> <dt> <strong>D_NO_SUCH_DEVICE</strong> <dd> No device with that name, or the device is not operational. </dl> <h3>RELATED INFORMATION</h3> <p> Currently no references. \ No newline at end of file +<h2>device_set_filter</h2> +<hr> +<p> +<strong>Function</strong> - Name an input filter for a device. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< device/device.h></strong> +<strong>#include< device/net_status.h></strong> + +<strong>kern_return_t device_set_filter</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>receive_port</var>, + <strong>mach_msg_type_name_t</strong> <var>receive_port_type</var>, + <strong>int</strong> <var>priority</var>, + <strong>filter_array_t</strong> <var>filter</var>, + <strong>mach_msg_type_number_t</strong> <var>filter_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] +A device port +<p> +<dt> <var>receive_port</var> +<dd> +[in filter send or receive (to be converted to send) right] +The port to +receive the input data that is selected by the filter. +<p> +<dt> <var>receive_port_type</var> +<dd> +[in scalar] +IPC type of the send right provided to the device; either +<strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>, +or <strong>MACH_MSG_TYPE_COPY_SEND</strong>. +<p> +<dt> <var>priority</var> +<dd> +[in scalar] +Used to order multiple receivers in an implementation +dependent way. +<p> +<dt> <var>filter</var> +<dd> +[pointer to in array of <var>filter_t</var>] +The address of an array of filter values. +<p> +<dt> <var>filter_count</var> +<dd> +[in scalar] +The size of the <var>filter</var> array (in 16-bit values). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_set_filter</strong> function provides a means by +which selected data +appearing at a device interface can be selected and routed to +a port. This service is +provided in support of network devices. +<p> +The filter command list consists of an array of up to <strong>NET_MAX_FILTER</strong> +(16-bit) values to be applied to incoming data "messages" to determine if +that data should be given to a particular input filter. +<p> +Each filter command list specifies a sequence of actions which leave a boolean +value on the top of an internal stack. Each 16-bit value of the command list +specifies a data (push) operation (high order <strong>NETF_NBPO</strong> +bits) as well as a binary operator (low order <strong>NETF_NBPA</strong> bits). +<p> +The value to be pushed onto the stack is chosen as follows: +<dl> +<dt> <strong>NETF_PUSHLIT</strong> +<dd> +Use the next 16-bit value of the filter as the value. +<dt> <strong>NETF_PUSHZERO</strong> +<dd> +Use 0 as the value. +<dt> <strong>NETF_PUSHWORD+</strong><var>N</var> +<dd> +Use 16-bit value <var>N</var> of the "data" portion of the message as the value. +<dt> <strong>NETF_PUSHHDR+</strong><var>N</var> +<dd> +Use 16-bit value <var>N</var> of the "header" portion of the message as the value. +<dt> <strong>NETF_PUSHIND</strong> +<dd> +Pops the top 32-bit value from the stack and then uses it to index the +16-bit value of the "data" portion of the message to be used as the +value. +<dt> <strong>NETF_PUSHHDRIND</strong> +<dd> +Pops the top 32-bit value from the stack and then uses it to index the +16-bit value of the "header" portion of the message to be used as the +value. +<dt> <strong>NETF_PUSHSTK+</strong><var>N</var> +<dd> +Use 32-bit value <var>N</var> of the stack (where the top of stack is value 0) as +the value. +<dt> <strong>NETF_NOPUSH</strong> +<dd> +Don't push a value. +</dl> +The unsigned value so chosen is promoted to a 32-bit value before being pushed. +<p> +Once a value is pushed (except for the case of <strong>NETF_NOPUSH</strong>), the top two +32-bit values of the stack are popped and a binary operator applied to them +(with the old top of stack as the second operand). The result +of the operator is +pushed on the stack. These operators are: +<dl> +<dt> <strong>NETF_NOP</strong> +<dd> +Don't pop off any values and do no operation. +<dt> <strong>NETF_EQ</strong> +<dd> +Perform an equal comparison. +<dt> <strong>NETF_LT</strong> +<dd> +Perform a less than comparison. +<dt> <strong>NETF_LE</strong> +<dd> +Perform a less than or equal comparison. +<dt> <strong>NETF_GT</strong> +<dd> +Perform a greater than comparison. +<dt> <strong>NETF_GE</strong> +<dd> +Perform a greater than or equal comparison. +<dt> <strong>NETF_AND</strong> +<dd> +Perform a bit-wise boolean AND operation. +<dt> <strong>NETF_OR</strong> +<dd> +Perform a bit-wise boolean inclusive OR operation. +<dt> <strong>NETF_XOR</strong> +<dd> +Perform a bit-wise boolean exclusive OR operation. +<dt> <strong>NETF_NEQ</strong> +<dd> +Perform a not equal comparison. +<dt> <strong>NETF_LSH</strong> +<dd> +Perform a left shift operation. +<dt> <strong>NETF_RSH</strong> +<dd> +Perform a right shift operation. +<dt> <strong>NETF_ADD</strong> +<dd> +Perform an addition. +<dt> <strong>NETF_SUB</strong> +<dd> +Perform a subtraction. +<dt> <strong>NETF_COR</strong> +<dd> +Perform an equal comparison. If the comparison is <strong>TRUE</strong>, terminate +the filter list. Otherwise, pop the result of the comparison off the stack. +<dt> <strong>NETF_CAND</strong> +<dd> +Perform an equal comparison. If the comparison is <strong>FALSE</strong>, terminate +the filter list. Otherwise, pop the result of the comparison off the stack. +<dt> <strong>NETF_CNOR</strong> +<dd> +Perform a not equal comparison. If the comparison is <strong>FALSE</strong>, +terminate the filter list. Otherwise, pop the result of the +comparison off the +stack. +<dt> <strong>NETF_CNAND</strong> +<dd> +Perform a not equal comparison. If the comparison is <strong>TRUE</strong>, terminate +the filter list. Otherwise, pop the result of the comparison off the stack. +</dl> +The scan of the filter list terminates when the filter list is emptied, or a +<strong>NETF_C</strong> operation terminates the list. At this time, if the final +value of the top of the stack is <strong>TRUE</strong>, then the message is accepted +for the filter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>D_DEVICE_DOWN</strong> +<dd> +Device has been shut down +<p> +<dt> <strong>D_INVALID_OPERATION</strong> +<dd> +No filter port was supplied. +<p> +<dt> <strong>D_NO_SUCH_DEVICE</strong> +<dd> +No device with that name, or the device is not operational. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Currently no references. diff --git a/osfmk/man/device_set_status.html b/osfmk/man/device_set_status.html index a55a2347a..bc1cd92c2 100755 --- a/osfmk/man/device_set_status.html +++ b/osfmk/man/device_set_status.html @@ -1 +1,70 @@ -<h2>device_set_status</h2> <hr> <p> <strong>Function</strong> - Set device status. <h3>SYNOPSIS</h3> <pre> <strong>#include< device/device.h></strong> <strong>kern_return_t device_set_status</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>dev_flavor_t</strong> <var>flavor</var>, <strong>dev_status_t</strong> <var>status</var>, <strong>mach_msg_type_number_t</strong> <var>status_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be manipulated. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of status information to set. <p> <dt> <var>status</var> <dd> [pointer to in array of natural-sized units] The status information to set. <p> <dt> <var>status_count</var> <dd> [in scalar] The size of the status information (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_set_status</strong> function sets device status. The possible values of <var>flavor</var> as well as the corresponding meanings are device dependent. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>D_DEVICE_DOWN</strong> <dd> Device has been shut down <p> <dt> <strong>D_IO_ERROR</strong> <dd> Hardware I/O error <p> <dt> <strong>D_NO_SUCH_DEVICE</strong> <dd> No device with that name, or the device is not operational. <p> <dt> <strong>D_OUT_OF_BAND</strong> <dd> Out-of-band condition occurred on device (such as typing <strong><Ctrl>-C</strong>). <p> <dt> <strong>D_READ_ONLY</strong> <dd> Data cannot be written to this device. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_get_status.html"><strong>device_get_status</strong></a>. \ No newline at end of file +<h2>device_set_status</h2> +<hr> +<p> +<strong>Function</strong> - Set device status. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< device/device.h></strong> + +<strong>kern_return_t device_set_status</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>dev_flavor_t</strong> <var>flavor</var>, + <strong>dev_status_t</strong> <var>status</var>, + <strong>mach_msg_type_number_t</strong> <var>status_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] +A device port to the device to be manipulated. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of status information to set. +<p> +<dt> <var>status</var> +<dd> +[pointer to in array of natural-sized units] +The status information to set. +<p> +<dt> <var>status_count</var> +<dd> +[in scalar] +The size of the status information (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_set_status</strong> function sets device status. +The possible values of <var>flavor</var> +as well as the corresponding meanings are device dependent. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>D_DEVICE_DOWN</strong> +<dd> +Device has been shut down +<p> +<dt> <strong>D_IO_ERROR</strong> +<dd> +Hardware I/O error +<p> +<dt> <strong>D_NO_SUCH_DEVICE</strong> +<dd> +No device with that name, or the device is not operational. +<p> +<dt> <strong>D_OUT_OF_BAND</strong> +<dd> +Out-of-band condition occurred on device (such as typing + <strong><Ctrl>-C</strong>). +<p> +<dt> <strong>D_READ_ONLY</strong> +<dd> +Data cannot be written to this device. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_get_status.html"><strong>device_get_status</strong></a>. diff --git a/osfmk/man/device_write.html b/osfmk/man/device_write.html index 20007edd7..20b3e8e61 100755 --- a/osfmk/man/device_write.html +++ b/osfmk/man/device_write.html @@ -1 +1,98 @@ -<h2>device_write</h2> <hr> <p> <strong>Function</strong> - Write a sequence of bytes to a specific device. <h3>SYNOPSIS</h3> <pre> <strong>#include<device/device.h></strong> <strong>kern_return_t device_write</strong> <strong>(device_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>reply_port</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_ptr_t</strong> <var>data</var>, <strong>mach_msg_type_number_t</strong> <var>data_count</var>, <strong>io_buf_len_t</strong> <var>io_buf_len_t</var><strong>);</strong> <strong>#include<device/device_request.h></strong> <strong>kern_return_t device_write_request</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>reply_port</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_ptr_t</strong> <var>data</var>, <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> <strong>kern_return_t ds_device_write_reply</strong> <strong>(mach_port_t</strong> <var>reply_port</var>, <strong>kern_return_t</strong> <var>return_code</var>, <strong>io_buf_len_t</strong> <var>bytes_written</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be written. <p> <dt> <var>reply_port</var> <dd> [in reply receive (to be converted to send-once) right] The port to which the reply message is to be sent. <p> <dt> <var>mode</var> <dd> [in scalar] I/O mode value. Meaningful options are: <dl> <p> <dt> <strong>D_NOWAIT</strong> <dd> Do not wait for I/O completion. </dl> <p> <dt> <var>recnum</var> <dd> [in scalar] Record number to be written. <p> <dt> <var>data</var> <dd> [pointer to in array of bytes] Data bytes to be written. <p> <dt> <var>data_count</var> <dd> [in scalar] Number of data bytes to be written. <p> <dt> <var>return_code</var> <dd> [in scalar] The return status code from the write. <p> <dt> <var>bytes_written</var> <dd> [out scalar, in for asynchronous form] Size of data transfer. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_write</strong> function writes a sequence of bytes to a device object. The meaning of <var>recnum</var> as well as the specific operation performed is device dependent. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_write_inband.html"><strong>device_write_inband</strong></a>, <a href="device_reply_server.html"><strong>device_reply_server</strong></a>. \ No newline at end of file +<h2>device_write</h2> +<hr> +<p> +<strong>Function</strong> - Write a sequence of bytes to a specific device. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<device/device.h></strong> + +<strong>kern_return_t device_write</strong> + <strong>(device_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>reply_port</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_ptr_t</strong> <var>data</var>, + <strong>mach_msg_type_number_t</strong> <var>data_count</var>, + <strong>io_buf_len_t</strong> <var>io_buf_len_t</var><strong>);</strong> + + +<strong>#include<device/device_request.h></strong> + +<strong>kern_return_t device_write_request</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>reply_port</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_ptr_t</strong> <var>data</var>, + <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> + + +<strong>kern_return_t ds_device_write_reply</strong> + <strong>(mach_port_t</strong> <var>reply_port</var>, + <strong>kern_return_t</strong> <var>return_code</var>, + <strong>io_buf_len_t</strong> <var>bytes_written</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] +A device port to the device to be written. +<p> +<dt> <var>reply_port</var> +<dd> +[in reply receive (to be converted to send-once) right] +The port to +which the reply message is to be sent. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] +I/O mode value. Meaningful options are: +<dl> +<p> +<dt> <strong>D_NOWAIT</strong> +<dd> +Do not wait for I/O completion. +</dl> +<p> +<dt> <var>recnum</var> +<dd> +[in scalar] +Record number to be written. +<p> +<dt> <var>data</var> +<dd> +[pointer to in array of bytes] +Data bytes to be written. +<p> +<dt> <var>data_count</var> +<dd> +[in scalar] +Number of data bytes to be written. +<p> +<dt> <var>return_code</var> +<dd> +[in scalar] +The return status code from the write. +<p> +<dt> <var>bytes_written</var> +<dd> +[out scalar, in for asynchronous form] +Size of data transfer. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_write</strong> function writes a sequence of bytes +to a device object. The +meaning of <var>recnum</var> as well as the specific operation performed is device +dependent. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_write_inband.html"><strong>device_write_inband</strong></a>, +<a href="device_reply_server.html"><strong>device_reply_server</strong></a>. diff --git a/osfmk/man/device_write_async.html b/osfmk/man/device_write_async.html index 84b077dca..99d595b0a 100755 --- a/osfmk/man/device_write_async.html +++ b/osfmk/man/device_write_async.html @@ -1 +1,69 @@ -<h2>device_write_async</h2> <hr> <p> <strong>System Trap</strong> - Write a sequence of bytes to a device object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t device_write_async</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>queue</var>, <strong>mach_port_t</strong> <var>request_id</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_ptr_t</strong> <var>data</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be read. <p> <dt> <var>queue</var> <dd> [in io_done queue send right] The port returned from io_done_queue_create. <p> <dt> <var>request_id</var> <dd> [in send right] An unique request identifier that will be passed back as part of the io_done_result structure. <p> <dt> <var>mode</var> <dd> [in scalar] I/O mode value. Meaningful options are: <p> <dl> <dt> <strong>D_NOWAIT</strong> <dd> Do not wait if data is unavailable. </dl> <p> <dt> <var>recnum</var> <dd> [in scalar] Record number to be read. <p> <dt> <var>data</var> <dd> [pointer to in array of bytes] Data bytes to be written. <p> <dt> <var>bytes_wanted</var> <dd> [in scalar] Size of data transfer. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_write_async</strong> function enqueues a write operation for a sequence of bytes to a device object. The meaning of recnum as well as the specific operation performed is device dependent. <h3>RETURN VALUES</h3> <p> <strong>device_write_async</strong> returns only invalid parameter errors. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, <a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, <a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>, <a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>. \ No newline at end of file +<h2>device_write_async</h2> +<hr> +<p> +<strong>System Trap</strong> - Write a sequence of bytes to a device object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t device_write_async</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>queue</var>, + <strong>mach_port_t</strong> <var>request_id</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_ptr_t</strong> <var>data</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] A device port to the device to be read. +<p> +<dt> <var>queue</var> +<dd> +[in io_done queue send right] The port returned from +io_done_queue_create. +<p> +<dt> <var>request_id</var> +<dd> +[in send right] An unique request identifier that will be passed back as +part of the io_done_result structure. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] I/O mode value. Meaningful options are: +<p> + <dl> +<dt> <strong>D_NOWAIT</strong> +<dd> +Do not wait if data is unavailable. + </dl> +<p> +<dt> <var>recnum</var> +<dd> +[in scalar] Record number to be read. +<p> +<dt> <var>data</var> +<dd> +[pointer to in array of bytes] Data bytes to be written. +<p> +<dt> <var>bytes_wanted</var> +<dd> +[in scalar] Size of data transfer. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_write_async</strong> function enqueues a write operation for a +sequence of bytes to a device object. The meaning of recnum as well as +the specific operation performed is device dependent. +<h3>RETURN VALUES</h3> +<p> +<strong>device_write_async</strong> returns only invalid parameter errors. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, +<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, +<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>, +<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>. diff --git a/osfmk/man/device_write_async_inband.html b/osfmk/man/device_write_async_inband.html index ff119ba66..28eb126f8 100755 --- a/osfmk/man/device_write_async_inband.html +++ b/osfmk/man/device_write_async_inband.html @@ -1 +1,71 @@ -<h2>device_write_async_inband</h2> <hr> <p> <strong>System Trap</strong> - Write a sequence of bytes "inband" to a device object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t device_write_async_inband</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>queue</var>, <strong>mach_port_t</strong> <var>request_id</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_ptr_t</strong> <var>data</var>, <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be read. <p> <dt> <var>queue</var> <dd> [in io_done queue send right] The port returned from io_done_queue_create. <p> <dt> <var>request_id</var> <dd> [in send right] An unique request identifier that will be passed back as part of the io_done_result structure. <p> <dt> <var>mode</var> <dd> [in scalar] I/O mode value. Meaningful options are: <p> <dl> <dt> <strong>D_NOWAIT</strong> <dd> Do not wait if data is unavailable. </dl> <p> <dt> <var>recnum</var> <dd> [in scalar] Record number to be read. <p> <dt> <var>data</var> <dd> [pointer to in array of bytes] Data bytes to be written. <p> <dt> <var>bytes_wanted</var> <dd> [in scalar] Size of data transfer. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_write_async_inband</strong> function enqueues a write operation for a sequence of bytes to a device object. The meaning of recnum as well as the specific operation performed is device dependent. This call differs from <strong>device_write_async</strong> in that the bytes to be written are sent "inband" in the request IPC message. <h3>RETURN VALUES</h3> <p> <strong>device_write_async_inband</strong> returns only invalid parameter errors. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, <a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, <a href="device_write_async.html"><strong>device_write_async</strong></a>, <a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>. \ No newline at end of file +<h2>device_write_async_inband</h2> +<hr> +<p> +<strong>System Trap</strong> - Write a sequence of bytes "inband" to a device object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t device_write_async_inband</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>queue</var>, + <strong>mach_port_t</strong> <var>request_id</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_ptr_t</strong> <var>data</var>, + <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] A device port to the device to be read. +<p> +<dt> <var>queue</var> +<dd> +[in io_done queue send right] The port returned from +io_done_queue_create. +<p> +<dt> <var>request_id</var> +<dd> +[in send right] An unique request identifier that will be passed back as +part of the io_done_result structure. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] I/O mode value. Meaningful options are: +<p> + <dl> +<dt> <strong>D_NOWAIT</strong> +<dd> +Do not wait if data is unavailable. + </dl> +<p> +<dt> <var>recnum</var> +<dd> +[in scalar] Record number to be read. +<p> +<dt> <var>data</var> +<dd> +[pointer to in array of bytes] Data bytes to be written. +<p> +<dt> <var>bytes_wanted</var> +<dd> +[in scalar] Size of data transfer. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_write_async_inband</strong> function enqueues a write operation for +a sequence of bytes to a device object. The meaning of recnum as +well as the specific operation performed is device dependent. This +call differs from <strong>device_write_async</strong> in that the bytes to be written +are sent "inband" in the request IPC message. +<h3>RETURN VALUES</h3> +<p> +<strong>device_write_async_inband</strong> returns only invalid parameter errors. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, +<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, +<a href="device_write_async.html"><strong>device_write_async</strong></a>, +<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>. diff --git a/osfmk/man/device_write_inband.html b/osfmk/man/device_write_inband.html index f7ff44b2f..07b5a977c 100755 --- a/osfmk/man/device_write_inband.html +++ b/osfmk/man/device_write_inband.html @@ -1 +1,97 @@ -<h2>device_write_inband</h2> <hr> <p> <strong>Function</strong> - Write a sequence of bytes "inband" to a device object. <h3>SYNOPSIS</h3> <pre> <strong>#include<device/device.h (device_write_inband)></strong> <strong>kern_return_t device_write_inband</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_ptr_inband_t</strong> <var>data</var>, <strong>mach_msg_type_number_t</strong> <var>data_count</var>, <strong>io_buf_len_t</strong> <var>io_buf_len_t</var><strong>);</strong> <strong>#include<device/device_request.h></strong> <strong>kern_return_t device_write_request_inband</strong> <strong>(mach_port_t</strong> <var>device</var>, <strong>mach_port_t</strong> <var>reply_port</var>, <strong>dev_mode_t</strong> <var>mode</var>, <strong>recnum_t</strong> <var>recnum</var>, <strong>io_buf_ptr_inband_t</strong> <var>data</var>, <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> <strong>kern_return_t ds_device_write_reply_inband</strong> <strong>(mach_port_t</strong> <var>reply_port</var>, <strong>kern_return_t</strong> <var>return_code</var>, <strong>io_buf_len_t</strong> <var>bytes_writte</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>device</var> <dd> [in device send right] A device port to the device to be written. <p> <dt> <var>reply_port</var> <dd> [in reply receive (to be converted to send-once) right] The port to which the reply message is to be sent. <p> <dt> <var>mode</var> <dd> [in scalar] I/O mode value. Meaningful options are: <dl> <p> <dt> <strong>D_NOWAIT</strong> <dd> Do not wait for I/O completion. </dl> <p> <dt> <var>recnum</var> <dd> [in scalar] Record number to be written. <p> <dt> <var>data</var> <dd> [pointer to in array of bytes] Data bytes to be written. <p> <dt> <var>data_count</var> <dd> [in scalar] Number of data bytes to be written. <p> <dt> <var>return_code</var> <dd> [in scalar] The return status code from the write. <p> <dt> <var>bytes_written</var> <dd> [out scalar, in for asynchronous form] Size of data transfer. </dl> <h3>DESCRIPTION</h3> <p> The <strong>device_write_inband</strong> function writes a sequence of bytes to a device object. The meaning of <var>recnum</var> as well as the specific operation performed is device dependent. This call differs from <strong>device_write</strong> in that the bytes to be written are sent "inband" in the request IPC message. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_write.html"><strong>device_write</strong></a>, <a href="device_reply_server.html"><strong>device_reply_server</strong></a>. \ No newline at end of file +<h2>device_write_inband</h2> +<hr> +<p> +<strong>Function</strong> - Write a sequence of bytes "inband" to a device object. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<device/device.h (device_write_inband)></strong> + +<strong>kern_return_t device_write_inband</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_ptr_inband_t</strong> <var>data</var>, + <strong>mach_msg_type_number_t</strong> <var>data_count</var>, + <strong>io_buf_len_t</strong> <var>io_buf_len_t</var><strong>);</strong> + + +<strong>#include<device/device_request.h></strong> + +<strong>kern_return_t device_write_request_inband</strong> + <strong>(mach_port_t</strong> <var>device</var>, + <strong>mach_port_t</strong> <var>reply_port</var>, + <strong>dev_mode_t</strong> <var>mode</var>, + <strong>recnum_t</strong> <var>recnum</var>, + <strong>io_buf_ptr_inband_t</strong> <var>data</var>, + <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> + + +<strong>kern_return_t ds_device_write_reply_inband</strong> + <strong>(mach_port_t</strong> <var>reply_port</var>, + <strong>kern_return_t</strong> <var>return_code</var>, + <strong>io_buf_len_t</strong> <var>bytes_writte</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>device</var> +<dd> +[in device send right] +A device port to the device to be written. +<p> +<dt> <var>reply_port</var> +<dd> +[in reply receive (to be converted to send-once) right] +The port to +which the reply message is to be sent. +<p> +<dt> <var>mode</var> +<dd> +[in scalar] +I/O mode value. Meaningful options are: +<dl> +<p> +<dt> <strong>D_NOWAIT</strong> +<dd> +Do not wait for I/O completion. +</dl> +<p> +<dt> <var>recnum</var> +<dd> +[in scalar] +Record number to be written. +<p> +<dt> <var>data</var> +<dd> +[pointer to in array of bytes] +Data bytes to be written. +<p> +<dt> <var>data_count</var> +<dd> +[in scalar] +Number of data bytes to be written. +<p> +<dt> <var>return_code</var> +<dd> +[in scalar] +The return status code from the write. +<p> +<dt> <var>bytes_written</var> +<dd> +[out scalar, in for asynchronous form] +Size of data transfer. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>device_write_inband</strong> function writes a sequence of bytes to a device +object. The meaning of <var>recnum</var> as well as the specific operation +performed is device dependent. This call differs from <strong>device_write</strong> +in that the bytes to be written are sent "inband" in the request IPC message. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_write.html"><strong>device_write</strong></a>, +<a href="device_reply_server.html"><strong>device_reply_server</strong></a>. diff --git a/osfmk/man/do_mach_notify_dead_name.html b/osfmk/man/do_mach_notify_dead_name.html index ffc3c74f4..2f3ffe6c8 100755 --- a/osfmk/man/do_mach_notify_dead_name.html +++ b/osfmk/man/do_mach_notify_dead_name.html @@ -1 +1,65 @@ -<h2>do_mach_notify_dead_name</h2> <hr> <strong>Server Interface</strong> - Handle the current instance of a dead-name notification. <p> <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t do_mach_notify_dead_name</strong> <strong>(notify_port_t</strong> <var>notify</var>, <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> <strong>kern_return_t do_seqnos_mach_notify_dead_name</strong> <strong>(notify_port_t</strong> <var>notify</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>notify</var> <dd> [in notify (receive) right] The port to which the notification was sent. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the notification port. <p> <dt> <var>name</var> <dd> [in scalar] The dead name. </dl> <h3>DESCRIPTION</h3> <p> A <strong>do_mach_notify_dead_name</strong> function is called by <strong>notify_server</strong> as the result of a kernel message indicating that the port name is now dead as the result of the associated receive right having died. In contrast, a port-deleted notification indicates that the port name is no longer usable (that is, it no longer names a valid right), typically as a result of the right so named being consumed or moved. <var>notify</var> is the port named via <strong>mach_port_request_notification</strong> or <strong>mach_msg</strong>. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="notify_server.html"><strong>notify_server</strong></a>, <a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>, <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, <a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>, <a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>, <a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>. \ No newline at end of file +<h2>do_mach_notify_dead_name</h2> +<hr> +<strong>Server Interface</strong> - Handle the current instance of a dead-name notification. +<p> +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t do_mach_notify_dead_name</strong> + <strong>(notify_port_t</strong> <var>notify</var>, + <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> + + +<strong>kern_return_t do_seqnos_mach_notify_dead_name</strong> + <strong>(notify_port_t</strong> <var>notify</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>notify</var> +<dd> +[in notify (receive) right] +The port to which the notification was sent. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the +notification port. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The dead name. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>do_mach_notify_dead_name</strong> function is called by <strong>notify_server</strong> +as the +result of a kernel message indicating that the port name is now +dead as the result +of the associated receive right having died. In contrast, a port-deleted +notification indicates that the port name is no longer usable +(that is, it no longer names +a valid right), typically as a result of the right so named being consumed or +moved. <var>notify</var> is the port named via <strong>mach_port_request_notification</strong> +or +<strong>mach_msg</strong>. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="notify_server.html"><strong>notify_server</strong></a>, +<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>, +<a href="mach_msg.html"><strong>mach_msg</strong></a>, +<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, +<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>, +<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>, +<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>. diff --git a/osfmk/man/do_mach_notify_no_senders.html b/osfmk/man/do_mach_notify_no_senders.html index cf19bea13..85c8bef88 100755 --- a/osfmk/man/do_mach_notify_no_senders.html +++ b/osfmk/man/do_mach_notify_no_senders.html @@ -1 +1,55 @@ -<h2>do_mach_notify_no_senders</h2> <hr> <p> <strong>Server Interface</strong> - Handle the current instance of a no-more-senders notification. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t do_mach_notify_no_senders</strong> <strong>(notify_port_t</strong> <var>notify</var>, <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong> <strong>kern_return_t do_seqnos_mach_notify_no_senders</strong> <strong>(notify_port_t</strong> <var>notify</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>notify</var> <dd> [in notify (receive) right] The port to which the notification was sent. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the notification port. <p> <dt> <var>mscount</var> <dd> [in scalar] The value the port's make-send count had when the notification was generated. </dl> <h3>DESCRIPTION</h3> <p> A <strong>do_mach_notify_no_senders</strong> function is called by <strong>notify_server</strong> as the result of a kernel message indicating that a receive right has no more senders. <var>notify</var> is the port named via <strong>mach_port_request_notification</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="notify_server.html"><strong>notify_server</strong></a>, <a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>, <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, <a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>, <a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>, <a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>. \ No newline at end of file +<h2>do_mach_notify_no_senders</h2> +<hr> +<p> +<strong>Server Interface</strong> - Handle the current instance of a no-more-senders notification. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t do_mach_notify_no_senders</strong> + <strong>(notify_port_t</strong> <var>notify</var>, + <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong> + + +<strong>kern_return_t do_seqnos_mach_notify_no_senders</strong> + <strong>(notify_port_t</strong> <var>notify</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>notify</var> +<dd> +[in notify (receive) right] +The port to which the notification was sent. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the +notification port. +<p> +<dt> <var>mscount</var> +<dd> +[in scalar] +The value the port's make-send count had when the +notification was generated. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>do_mach_notify_no_senders</strong> function is called by +<strong>notify_server</strong> as the +result of a kernel message indicating that a receive right has no more senders. +<var>notify</var> is the port named via <strong>mach_port_request_notification</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="notify_server.html"><strong>notify_server</strong></a>, +<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>, +<a href="mach_msg.html"><strong>mach_msg</strong></a>, +<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, +<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>, +<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>, +<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>. diff --git a/osfmk/man/do_mach_notify_send_once.html b/osfmk/man/do_mach_notify_send_once.html index d5a8242f0..2c6051394 100755 --- a/osfmk/man/do_mach_notify_send_once.html +++ b/osfmk/man/do_mach_notify_send_once.html @@ -1 +1,48 @@ -<h2>do_mach_notify_send_once</h2> <hr> <p> <strong>Server Interface</strong> - Handle the current instance of a send-once notification. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t do_mach_notify_send_once</strong> <strong>(notify_port_t</strong> <var>notify</var><strong>)</strong> <strong>kern_return_t do_seqnos_mach_notify_send_once</strong> <strong>(notify_port_t</strong> <var>notify</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>notify</var> <dd> [in notify (receive) right] The port to which the notification was sent. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the notification port. </dl> <h3>DESCRIPTION</h3> <p> A <strong>do_mach_notify_send_once</strong> function is called by <strong>notify_server</strong> as the result of a kernel message indicating that a send-once right was in any way destroyed. <var>notify</var> is the port for which a send-once right was destroyed. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="notify_server.html"><strong>notify_server</strong></a>, <a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>, <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, <a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>, <a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>, <a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>. \ No newline at end of file +<h2>do_mach_notify_send_once</h2> +<hr> +<p> +<strong>Server Interface</strong> - Handle the current instance of a send-once notification. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t do_mach_notify_send_once</strong> + <strong>(notify_port_t</strong> <var>notify</var><strong>)</strong> + + +<strong>kern_return_t do_seqnos_mach_notify_send_once</strong> + <strong>(notify_port_t</strong> <var>notify</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>notify</var> +<dd> +[in notify (receive) right] +The port to which the notification was sent. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the +notification port. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>do_mach_notify_send_once</strong> function is called by <strong>notify_server</strong> +as the result +of a kernel message indicating that a send-once right was in +any way destroyed. +<var>notify</var> is the port for which a send-once right was destroyed. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="notify_server.html"><strong>notify_server</strong></a>, +<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>, +<a href="mach_msg.html"><strong>mach_msg</strong></a>, +<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, +<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>, +<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>, +<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>. diff --git a/osfmk/man/etap_get_info.html b/osfmk/man/etap_get_info.html index 0814833ae..db4368ee7 100755 --- a/osfmk/man/etap_get_info.html +++ b/osfmk/man/etap_get_info.html @@ -1 +1,93 @@ -<h2>etap_get_info</h2> <hr> <p> <strong>Function</strong> - Map ETAP buffers and tables into server's address space. <h3>SYNOPSIS</h3> <pre> <strong>#include<mach/etap.h></strong> <strong>kern_return_t etap_get_info</strong> <strong>(host_priv_t</strong> <var>priv_port</var>, <strong>int</strong> <var>int</var>, <strong>int</strong> <var>int</var>, <strong>vm_offset_t</strong> <var>vm_offset_t</var>, <strong>vm_offset_t</strong> <var>vm_offset_t</var>, <strong>int</strong> <var>int</var>, <strong>int</strong> <var>int</var>, <strong>int</strong> <var>int</var>, <strong>int</strong> <var>int</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>priv_port</var> <dd> the name of the Server's privileged device port (server_device_port), granting the Server access to this service. <p> <dt> <var>et_entries</var> <dd> used to return number of entries in the event table. <p> <dt> <var>st_entries</var> <dd> used to return number of entries in the subsystem table. <p> <dt> <var>et_offset</var> <dd> used to return the event table's page offset. <p> <dt> <var>st_offset</var> <dd> used to return the subsystem table's page offset. <p> <dt> <var>cb_width</var> <dd> returns the current cumulative buffer interval width. <p> <dt> <var>mb_size</var> <dd> returns the size of the monitored buffers, <p> <dt> <var>mb_entries</var> <dd> returns the maximum number of entries in a monitored buffer. <p> <dt> <var>mb_cpus</var> <dd> returns the number of allocated monitored buffers (or supported CPUs). </dl> <h3>DESCRIPTION</h3> <p> The <strong>etap_get_info</strong> interface provides the user space etap server or daemon with configuration and location information pertaining to the kernel's internal ETAP buffers; this information enables the caller to properly map the ETAP buffers and tables into its address space. When mapping is successfully completed, the Server displays the ETAP configuration on the console. The configuration output will resemble the following: <pre> ETAP configuration [ee:108 se:8 eo:a60 so:acc cw:0 ms:1008008 me:36 mc:1] ETAP event table mapped ETAP subsystem table mapped ETAP monitored buffer #0 mapped </pre> <p> The values between the brackets correspond with the arguments returned by the <strong>etap_get_info</strong> call (listed above). For example, "ee:108" indicates that the event table contains 108 ETAP event types and "mc:1" indicates that one monitored buffer has been allocated. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_SUCCESS</strong> <dd> The call was performed successfully. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="etap_probe.html"><strong>etap_probe</strong></a>, <a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>, <a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>, <a href="etap_trace_event.html"><strong>etap_get_info</strong></a>. \ No newline at end of file +<h2>etap_get_info</h2> +<hr> +<p> +<strong>Function</strong> - Map ETAP buffers and tables into server's address space. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<mach/etap.h></strong> + +<strong>kern_return_t etap_get_info</strong> + <strong>(host_priv_t</strong> <var>priv_port</var>, + <strong>int</strong> <var>int</var>, + <strong>int</strong> <var>int</var>, + <strong>vm_offset_t</strong> <var>vm_offset_t</var>, + <strong>vm_offset_t</strong> <var>vm_offset_t</var>, + <strong>int</strong> <var>int</var>, + <strong>int</strong> <var>int</var>, + <strong>int</strong> <var>int</var>, + <strong>int</strong> <var>int</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>priv_port</var> +<dd> +the name of the Server's privileged device port (server_device_port), + granting the Server access to this service. +<p> +<dt> <var>et_entries</var> +<dd> +used to return number of entries in the event table. +<p> +<dt> <var>st_entries</var> +<dd> +used to return number of entries in the subsystem table. +<p> +<dt> <var>et_offset</var> +<dd> +used to return the event table's page offset. +<p> +<dt> <var>st_offset</var> +<dd> +used to return the subsystem table's page offset. +<p> +<dt> <var>cb_width</var> +<dd> +returns the current cumulative buffer interval width. +<p> +<dt> <var>mb_size</var> +<dd> +returns the size of the monitored buffers, +<p> +<dt> <var>mb_entries</var> +<dd> +returns the maximum number of entries in a monitored buffer. +<p> +<dt> <var>mb_cpus</var> +<dd> +returns the number of allocated monitored buffers (or supported CPUs). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>etap_get_info</strong> interface provides the user space +etap server or daemon with configuration and location information pertaining +to the kernel's internal ETAP buffers; this information enables the caller +to properly map the ETAP buffers and tables into its address +space. When mapping is successfully completed, the Server displays the +ETAP configuration on the console. The configuration output will +resemble the following: +<pre> + ETAP configuration [ee:108 se:8 eo:a60 so:acc cw:0 ms:1008008 me:36 mc:1] + ETAP event table mapped + ETAP subsystem table mapped + ETAP monitored buffer #0 mapped +</pre> +<p> +The values between the brackets correspond with the arguments returned +by the <strong>etap_get_info</strong> call (listed +above). For example, "ee:108" indicates that the event table contains +108 ETAP event types and "mc:1" indicates that one monitored buffer +has been allocated. +<h3>RETURN VALUES</h3> +<dl> + <dt> <strong>KERN_SUCCESS</strong> + <dd> + The call was performed successfully. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="etap_probe.html"><strong>etap_probe</strong></a>, +<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>, +<a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>, +<a href="etap_trace_event.html"><strong>etap_get_info</strong></a>. diff --git a/osfmk/man/etap_probe.html b/osfmk/man/etap_probe.html index 9d105f15b..f3b8eadfc 100755 --- a/osfmk/man/etap_probe.html +++ b/osfmk/man/etap_probe.html @@ -1 +1,63 @@ -<h2>etap_probe</h2> <hr> <p> <strong>System Trap</strong> - Record event data in the kernel's ETAP buffer(s). <h3>SYNOPSIS</h3> <pre> <strong>#include<mach/etap.h></strong> <strong>kern_return_t etap_probe</strong> <strong>(int</strong> <var>event_id</var>, <strong>event_id</strong> <var>data_size</var>, <strong>etap_data_t</strong> <var>etap_data_t</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>event_id</var> <dd> A user defined value used to identify the event. <p> <dt> <var>data_size</var> <dd> The size (in bytes) of the data being passed. Note: The data size is limited to ETAP_DATA_SIZE, (defined in <strong>mach/etap.h</strong>). <p> <dt> <var>data</var> <dd> A pointer to the event data being passed. </dl> <h3>DESCRIPTION</h3> <p> Application programmers may instrument their applications with user-level probes, using the <strong>etap_probe</strong> system call. All event data passed to the kernel via <strong>etap_probe</strong> is recorded in the kernel's ETAP monitored buffer(s). Each record includes a time stamp. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_SUCCESS</strong> <dd> The call was performed successfully. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified data size exceeds ETAP_DATA_SIZE. <p> <dt> <strong>KERN_NO_ACCESS</strong> <dd> The tracing of user events is currently enabled. <p> <dt> <strong>KERN_FAILURE</strong> <dd> ETAP is not configured in the kernel. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>, <a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>, <a href="etap_get_info.html"><strong>etap_get_info</strong></a>. \ No newline at end of file +<h2>etap_probe</h2> +<hr> +<p> +<strong>System Trap</strong> - Record event data in the kernel's +ETAP buffer(s). +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<mach/etap.h></strong> + +<strong>kern_return_t etap_probe</strong> + <strong>(int</strong> <var>event_id</var>, + <strong>event_id</strong> <var>data_size</var>, + <strong>etap_data_t</strong> <var>etap_data_t</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>event_id</var> +<dd> +A user defined value used to identify the event. +<p> +<dt> <var>data_size</var> +<dd> +The size (in bytes) of the data being passed. +Note: The data size is limited to ETAP_DATA_SIZE, +(defined in <strong>mach/etap.h</strong>). +<p> +<dt> <var>data</var> +<dd> +A pointer to the event data being passed. +</dl> +<h3>DESCRIPTION</h3> +<p> +Application programmers may instrument their applications with +user-level probes, using the +<strong>etap_probe</strong> system call. All +event data passed to the kernel via +<strong>etap_probe</strong> is recorded in the +kernel's ETAP monitored buffer(s). Each record includes a time stamp. +<h3>RETURN VALUES</h3> +<dl> + <dt> <strong>KERN_SUCCESS</strong> + <dd> + The call was performed successfully. +<p> + <dt> <strong>KERN_INVALID_ARGUMENT</strong> + <dd> + The specified data size exceeds ETAP_DATA_SIZE. +<p> + <dt> <strong>KERN_NO_ACCESS</strong> + <dd> + The tracing of user events is currently enabled. +<p> + <dt> <strong>KERN_FAILURE</strong> + <dd> + ETAP is not configured in the kernel. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>, +<a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>, +<a href="etap_get_info.html"><strong>etap_get_info</strong></a>. diff --git a/osfmk/man/etap_trace_event.html b/osfmk/man/etap_trace_event.html index 46f16dc25..a56ff4145 100755 --- a/osfmk/man/etap_trace_event.html +++ b/osfmk/man/etap_trace_event.html @@ -1 +1,108 @@ -<h2>etap_trace_event</h2> <hr> <p> <strong>System Trap</strong> - manipulate event probes and lock event tracing. <h3>SYNOPSIS</h3> <pre> <strong>#include<mach/etap.h></strong> <strong>kern_return_t etap_trace_event</strong> <strong>(etap_data_t</strong> <var>mode</var>, <strong>mode</strong> <var>type</var>, <strong>boolean_t</strong> <var>enable</var>, <strong>enable</strong> <var>nargs</var>, <strong>mode</strong> <var>mode</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>mode</var> <dd> indicates the desired trace flavor or reset option and may be one, or more, of the following: <ul> <p> <li> ETAP_CUMULATIVE: cumulative lock event trace mode. <p> <li> ETAP_MONITORED: monitored event trace mode (for probes or locks) <p> <li> ETAP_RESET: reset mode, clears all trace status and cumulative buffer entries </ul> <p> <dt> <var>type</var> <dd> used when measuring lock event contention or durations and may be one, or more, of the following: <ul> <p> <li> ETAP_CONTENT <p> <li> ETAP_DURATION </ul> <p> <dt> <var>enable</var> <dd> a boolean value indicattin whether the event trace operation is to be enabled (TRUE) or disabled (FALSE). <p> <dt> <var>nargs</var> <dd> specifies how many arguments are passed in the args array. <p> <dt> <var>args</var> <dd> an array, each element of which is a character string representing a specific subsystem or event type. These values must correspond to the ones the kernel uses to represent the same subsystems and event types. The maximum length of a character string is EVENT_NAME_LENGTH (defined in <strong>mach/etap.h</strong>). </dl> <h3>DESCRIPTION</h3> <p> The <strong>etap_trace_event</strong> system call is used to enable and disable kernel event probes (of a specified type) and all modes of lock event tracing. The call also supports a reset option, where the cumulative buffer data and all event type tracing is reset to zero. When the reset option is used, a new interval width can also be defined, using the <var>nargs</var> parameter. <p> To reset the ETAP instrumentation, the system call would utilize the mode parameter, passing the value of ETAP_RESET (All other parameters may equal NULL). If, at the time of reset, the <var>nargs</var> parameter is assigned a value, then the cumulative buffer interval width will be adjusted to be the size of that value. For example, the following system call would reset the ETAP instrumentation and adjust the cumulative buffer's interval width to 100ms: <pre> etap_trace_event(ETAP_RESET, 0, 0, 100, 0); </pre> <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_SUCCESS</strong> <dd> The call was performed successfully. <p> <dt> <strong>KERN_NO_SPACE</strong> <dd> A shortage of kernel resources prevented the operation from completing; the kernel has cleaned up all residual state (the error indicates a "clean" failure). <p> <dt> <strong>KERN_FAILURE</strong> <dd> ETAP is not configured in the kernel. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="etap_probe.html"><strong>etap_probe</strong></a>, <a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>, <a href="etap_get_info.html"><strong>etap_get_info</strong></a>. \ No newline at end of file +<h2>etap_trace_event</h2> +<hr> +<p> +<strong>System Trap</strong> - +manipulate event probes and lock event tracing. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<mach/etap.h></strong> + +<strong>kern_return_t etap_trace_event</strong> + <strong>(etap_data_t</strong> <var>mode</var>, + <strong>mode</strong> <var>type</var>, + <strong>boolean_t</strong> <var>enable</var>, + <strong>enable</strong> <var>nargs</var>, + <strong>mode</strong> <var>mode</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>mode</var> +<dd> +indicates the desired trace flavor or reset option and may be one, +or more, of the following: +<ul> +<p> + <li> +ETAP_CUMULATIVE: cumulative lock event trace mode. + <p> +<li> +ETAP_MONITORED: monitored event trace mode (for probes or locks) +<p> +<li> +ETAP_RESET: reset mode, clears all trace status and cumulative buffer entries +</ul> +<p> +<dt> <var>type</var> +<dd> +used when measuring lock event contention or durations +and may be one, or more, of the following: +<ul> +<p> + <li> +ETAP_CONTENT +<p> + <li> +ETAP_DURATION +</ul> +<p> +<dt> <var>enable</var> +<dd> +a boolean value indicattin whether the event trace operation is +to be enabled (TRUE) or disabled (FALSE). +<p> +<dt> <var>nargs</var> +<dd> +specifies how many arguments are passed in the args array. +<p> +<dt> <var>args</var> +<dd> +an array, each element of which is a character string +representing a specific subsystem or event type. These values must +correspond to the ones the kernel uses to represent the same +subsystems and event types. The maximum length of a character string +is EVENT_NAME_LENGTH (defined in <strong>mach/etap.h</strong>). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>etap_trace_event</strong> system call is used to enable +and disable kernel event probes (of a specified type) and all modes of lock event +tracing. The call also supports a reset option, where the cumulative +buffer data and all event type tracing is reset to zero. When the +reset option is used, a new interval width can also be defined, using +the <var>nargs</var> parameter. +<p> +To reset the ETAP instrumentation, +the system call would utilize the mode parameter, passing the value of +ETAP_RESET (All other parameters may equal NULL). If, at the time of +reset, the <var>nargs</var> parameter is assigned a value, then the +cumulative buffer interval width will be adjusted to be the size of +that value. For example, the following system call would reset the +ETAP instrumentation and adjust the cumulative buffer's interval width +to 100ms: +<pre> + etap_trace_event(ETAP_RESET, 0, 0, 100, 0); + +</pre> +<h3>RETURN VALUES</h3> +<dl> + <dt> <strong>KERN_SUCCESS</strong> + <dd> + The call was performed successfully. +<p> + <dt> <strong>KERN_NO_SPACE</strong> + <dd> + A shortage of kernel resources prevented the operation from completing; + the kernel has cleaned up all residual state (the error indicates a "clean" + failure). +<p> + <dt> <strong>KERN_FAILURE</strong> + <dd> + ETAP is not configured in the kernel. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="etap_probe.html"><strong>etap_probe</strong></a>, +<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>, +<a href="etap_get_info.html"><strong>etap_get_info</strong></a>. diff --git a/osfmk/man/etap_trace_thread.html b/osfmk/man/etap_trace_thread.html index 2a5b356f9..3e4d7d6cc 100755 --- a/osfmk/man/etap_trace_thread.html +++ b/osfmk/man/etap_trace_thread.html @@ -1 +1,49 @@ -<h2>etap_trace_thread</h2> <hr> <p> <strong>Function</strong> - Set a thread's ETAP trace status. <h3>SYNOPSIS</h3> <pre> <strong>#include<mach/etap.h></strong> <strong>kern_return_t etap_trace_thread</strong> <strong>(thread_act_t</strong> <var>target_thread</var>, <strong>boolean_t</strong> <var>active</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_thread</var> <dd> The port of the thread who's ETAP trace status will be toggled. <p> <dt> <var>active</var> <dd> The boolean value (either TRUE or FALSE) stating whether the thread's ETAP trace status will be activated or not. Passing TRUE will enable the thread's trace status and FALSE will deactivate it. </dl> <h3>DESCRIPTION</h3> <p> The <strong>etap_trace_thread</strong> system call is used to toggle the ETAP trace status of a thread. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_SUCCESS</strong> <dd> The call was performed successfully. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The value of <var>target_thread</var> does not name a valid thread. <p> <dt> <strong>KERN_FAILURE</strong> <dd> ETAP is not configured in the kernel. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="etap_probe.html"><strong>etap_probe</strong></a>, <a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>, <a href="etap_get_info.html"><strong>etap_get_info</strong></a>. \ No newline at end of file +<h2>etap_trace_thread</h2> +<hr> +<p> +<strong>Function</strong> - Set a thread's ETAP trace status. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<mach/etap.h></strong> + +<strong>kern_return_t etap_trace_thread</strong> + <strong>(thread_act_t</strong> <var>target_thread</var>, + <strong>boolean_t</strong> <var>active</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_thread</var> +<dd> +The port of the thread who's ETAP trace status will be toggled. +<p> +<dt> <var>active</var> +<dd> +The boolean value (either TRUE or FALSE) stating whether the thread's +ETAP trace status will be activated or not. Passing TRUE will enable +the thread's trace status and FALSE will deactivate it. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>etap_trace_thread</strong> system call is used to +toggle the ETAP trace status of a thread. +<h3>RETURN VALUES</h3> +<dl> + <dt> <strong>KERN_SUCCESS</strong> + <dd> + The call was performed successfully. +<p> + <dt> <strong>KERN_INVALID_ARGUMENT</strong> + <dd> + The value of <var>target_thread</var> does not name a valid thread. +<p> + <dt> <strong>KERN_FAILURE</strong> + <dd> + ETAP is not configured in the kernel. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="etap_probe.html"><strong>etap_probe</strong></a>, +<a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>, +<a href="etap_get_info.html"><strong>etap_get_info</strong></a>. diff --git a/osfmk/man/evc_wait.html b/osfmk/man/evc_wait.html index 18fe88d58..f29487eb5 100755 --- a/osfmk/man/evc_wait.html +++ b/osfmk/man/evc_wait.html @@ -1 +1,50 @@ -<h2>evc_wait</h2> <hr> <p> <strong>System Trap</strong> - Wait for a kernel (device) signalled event. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t evc_wait</strong> <strong>(unsigned int</strong> <var>event</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>event</var> <dd> [in scalar] The task local event ID of the kernel event object. </dl> <h3>DESCRIPTION</h3> <p> The <strong>evc_wait</strong> function causes the invoking thread to wait until the specified kernel (device) generated <var>event</var> occurs. Device drivers (typically mapped devices intended to be supported by user space drivers) may supply an <var>event</var> service. The <var>event</var> service defines one or more <var>event</var> objects, named by task local <var>event</var> IDs. Each of these <var>event</var> objects has an associated <var>event</var> count, initially zero. Whenever the associated <var>event</var> occurs (typically a device interrupt), the <var>event</var> count is incremented. If this count is zero when <strong>evc_wait</strong> is called, the calling thread waits for the next <var>event</var> to occur. Only one thread may be waiting for the <var>event</var> to occur. If the count is non-zero when <strong>evc_wait</strong> is called, the count is simply decremented without causing the thread to wait. The <var>event</var> count guarantees that no <var>event</var>s are lost. <h3>NOTES</h3> <p> The typical use of this service is within user space device drivers. When a device interrupt occurs, the (in this case, simple) kernel device driver would place device status in a shared (with the user device driver) memory window (established by <strong>device_map</strong>) and signal the associated <var>event</var>. The user space device driver would normally be waiting with <strong>evc_wait</strong>. The user thread then wakes, processes the device status, typically interacting with the device via its shared memory window, then waits for the next interrupt. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_NO_SPACE</strong> <dd> There is already a thread waiting for this event. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="device_map.html"><strong>device_map</strong></a>. \ No newline at end of file +<h2>evc_wait</h2> +<hr> +<p> +<strong>System Trap</strong> - Wait for a kernel (device) signalled event. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t evc_wait</strong> + <strong>(unsigned int</strong> <var>event</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>event</var> +<dd> +[in scalar] The task local event ID of the kernel event object. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>evc_wait</strong> function causes the invoking thread to wait until the +specified kernel (device) generated <var>event</var> occurs. Device drivers +(typically mapped devices intended to be supported by user space +drivers) may supply an <var>event</var> service. The <var>event</var> service defines one +or more <var>event</var> objects, named by task local <var>event</var> IDs. Each of these +<var>event</var> objects has an associated <var>event</var> count, initially zero. Whenever +the associated <var>event</var> occurs (typically a device interrupt), the <var>event</var> +count is incremented. If this count is zero when <strong>evc_wait</strong> is called, +the calling thread waits for the next <var>event</var> to occur. Only one thread +may be waiting for the <var>event</var> to occur. If the count is non-zero when +<strong>evc_wait</strong> is called, the count is simply decremented without causing +the thread to wait. The <var>event</var> count guarantees that no <var>event</var>s are +lost. +<h3>NOTES</h3> +<p> +The typical use of this service is within user space device +drivers. When a device interrupt occurs, the (in this case, simple) +kernel device driver would place device status in a shared (with the +user device driver) memory window (established by <strong>device_map</strong>) and +signal the associated <var>event</var>. The user space device driver would +normally be waiting with <strong>evc_wait</strong>. The user thread then wakes, +processes the device status, typically interacting with the device via +its shared memory window, then waits for the next interrupt. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>KERN_NO_SPACE</strong> +<dd> +There is already a thread waiting for this event. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="device_map.html"><strong>device_map</strong></a>. diff --git a/osfmk/man/exc_server.html b/osfmk/man/exc_server.html index 3bc56b110..9d1c2a4e3 100755 --- a/osfmk/man/exc_server.html +++ b/osfmk/man/exc_server.html @@ -1 +1,60 @@ -<h2>exc_server</h2> <hr> <p> <strong>Function</strong> - Handle kernel-reported thread exception. <h3>SYNOPSIS</h3> <pre> <strong>boolean_t exc_server</strong> <strong>(mach_msg_header_t</strong> <var>request_msg</var>, <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>in_msg</var> <dd> [pointer to in structure] The exception message received from the kernel. <p> <dt> <var>out_msg</var> <dd> [out structure] A reply message. </dl> <h3>DESCRIPTION</h3> <p> The <strong>exc_server</strong> function is the MIG generated server handling function to handle messages from the kernel relating to the occurrence of an exception in a thread. Such messages are delivered to the exception port set via <strong>thread_set_exception_ports</strong> or <strong>task_set_exception_ports</strong>. When an exception occurs in a thread, the thread sends an exception message to its exception port, blocking in the kernel waiting for the receipt of a reply. The <strong>exc_server</strong> function performs all necessary argument handling for this kernel message and calls <strong>catch_exception_raise</strong>, <strong>catch_exception_raise_state</strong> or <strong>catch_exception_raise_state_identity</strong>, which should handle the exception. If the called routine returns <strong>KERN_SUCCESS</strong>, a reply message will be sent, allowing the thread to continue from the point of the exception; otherwise, no reply message is sent and the called routine must have dealt with the exception thread directly. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>TRUE</strong> <dd> The message was handled and the appropriate function was called. <p> <dt> <strong>FALSE</strong> <dd> The message did not apply to the exception mechanism and no other action was taken. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="catch_exception_raise.html"><strong>catch_exception_raise<strong></a>. \ No newline at end of file +<h2>exc_server</h2> +<hr> +<p> +<strong>Function</strong> - Handle kernel-reported thread exception. +<h3>SYNOPSIS</h3> +<pre> +<strong>boolean_t exc_server</strong> + <strong>(mach_msg_header_t</strong> <var>request_msg</var>, + <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>in_msg</var> +<dd> +[pointer to in structure] +The exception message received from the +kernel. +<p> +<dt> <var>out_msg</var> +<dd> +[out structure] +A reply message. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>exc_server</strong> function is the MIG generated server +handling function to +handle messages from the kernel relating to the occurrence of +an exception in a +thread. Such messages are delivered to the exception port set via +<strong>thread_set_exception_ports</strong> or <strong>task_set_exception_ports</strong>. +When an exception occurs in a +thread, the thread sends an exception message to its exception port, blocking in +the kernel waiting for the receipt of a reply. The <strong>exc_server</strong> +function performs +all necessary argument handling for this kernel message and calls +<strong>catch_exception_raise</strong>, <strong>catch_exception_raise_state</strong> or +<strong>catch_exception_raise_state_identity</strong>, which should handle the +exception. If the called routine +returns <strong>KERN_SUCCESS</strong>, a reply message will be sent, allowing +the thread to +continue from the point of the exception; otherwise, no reply message is sent +and the called routine must have dealt with the exception thread directly. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The message was handled and the appropriate function was called. +<p> +<dt> <strong>FALSE</strong> +<dd> +The message did not apply to the exception mechanism and no other +action was taken. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="catch_exception_raise.html"><strong>catch_exception_raise<strong></a>. diff --git a/osfmk/man/host_adjust_time.html b/osfmk/man/host_adjust_time.html index 8912859af..32cbb9923 100755 --- a/osfmk/man/host_adjust_time.html +++ b/osfmk/man/host_adjust_time.html @@ -1 +1,42 @@ -<h2>host_adjust_time</h2> <hr> <p> <strong>Function</strong> - Gradually change the time. <h3>SYNOPSIS</h3> <pre> <strong>#include< mach/mach_host.h></strong> <strong>kern_return_t host_adjust_time</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>time_value_t</strong> <var>new_adjustment</var>, <strong>time_value_t</strong> <var>old_adjustment</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control port] The control port the host for which the time is to be set. <p> <dt> <var>new_adjustment</var> <dd> [in structure] New adjustment value. <p> <dt> <var>old_adjustment</var> <dd> [out structure] Old adjustment value. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_adjust_time</strong> function arranges for the time on a specified host to be gradually changed by an adjustment value. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_get_time.html"><strong>host_get_time</strong></a>, <a href="host_set_time.html"><strong>host_set_time</strong></a>. <p> Data Structures: time_value. \ No newline at end of file +<h2>host_adjust_time</h2> +<hr> +<p> +<strong>Function</strong> - Gradually change the time. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< mach/mach_host.h></strong> + +<strong>kern_return_t host_adjust_time</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>time_value_t</strong> <var>new_adjustment</var>, + <strong>time_value_t</strong> <var>old_adjustment</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control port] The control port the host for which the time is to be set. +<p> +<dt> <var>new_adjustment</var> +<dd> +[in structure] New adjustment value. +<p> +<dt> <var>old_adjustment</var> +<dd> +[out structure] Old adjustment value. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_adjust_time</strong> function arranges for the time on a specified host to be gradually changed by an adjustment value. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_get_time.html"><strong>host_get_time</strong></a>, +<a href="host_set_time.html"><strong>host_set_time</strong></a>. +<p> +Data Structures: +time_value. diff --git a/osfmk/man/host_basic_info.html b/osfmk/man/host_basic_info.html index 2a30d3187..b14209c2f 100755 --- a/osfmk/man/host_basic_info.html +++ b/osfmk/man/host_basic_info.html @@ -1 +1,86 @@ -<h2>host_basic_info</h2> <hr> <p> <strong>Structure</strong> - Used to present basic information about a host. <h3>SYNOPSIS</h3> <pre> <strong>struct host_basic_info</strong> <strong>{</strong> <strong>integer_t</strong> <var>max_cpus</var><strong>;</strong> <strong>integer_t</strong> <var>avail_cpus</var><strong>;</strong> <strong>vm_size_t</strong> <var>memory_size</var><strong>;</strong> <strong>cpu_type_t</strong> <var>cpu_type</var><strong>;</strong> <strong>cpu_subtype_t</strong> <var>cpu_subtype</var><strong>;</strong> <strong>cpu_threadtype_t</strong> <var>cpu_threadtype</var><strong>;</strong> <strong>integer_t</strong> <var>physical_cpu</var><strong>;</strong> <strong>integer_t</strong> <var>physical_cpu_max</var><strong>;</strong> <strong>integer_t</strong> <var>logical_cpu</var><strong>;</strong> <strong>integer_t</strong> <var>logical_cpu_max</var><strong>;</strong> <strong>uint64_t</strong> <var>max_mem</var><strong>;</strong> <strong>};</strong> <strong>typedef struct host_basic_info* host_basic_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>max_cpus</var> <dd> Maximum number of CPUs possible <p> <dt> <var>avail_cpus</var> <dd> Number of CPUs now available <p> <dt> <var>memory_size</var> <dd> Size of memory in bytes, capped at 2 GB <p> <dt> <var>cpu_type</var> <dd> CPU type <p> <dt> <var>cpu_subtype</var> <dd> CPU sub-type <p> <dt> <var>cpu_threadtype</var> <dd> CPU thread-type <p> <dt> <var>physical_cpu</var> <dd> Number of physical CPUs now available <p> <dt> <var>physical_cpu_max</var> <dd> Maximum number of physical CPUs possible <p> <dt> <var>logical_cpu</var> <dd> Number of logical CPUs now available <p> <dt> <var>logical_cpu_max</var> <dd> Maximum number of logical CPUs possible <p> <dt> <var>max_mem</var> <dd> Actual size of physical memory in bytes </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_basic_info</strong> structure defines the basic information available about a host. <h3>NOTES</h3> <p> This structure is machine word length specific because of the memory size returned. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_info.html"><strong>host_info</strong></a>. <p> Data Structures: <a href="host_load_info.html"><strong>host_load_info</strong></a>, <a href="host_sched_info.html"><strong>host_sched_info</strong></a>. \ No newline at end of file +<h2>host_basic_info</h2> +<hr> +<p> +<strong>Structure</strong> - Used to present basic information about a host. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct host_basic_info</strong> +<strong>{</strong> + <strong>integer_t</strong> <var>max_cpus</var><strong>;</strong> + <strong>integer_t</strong> <var>avail_cpus</var><strong>;</strong> + <strong>vm_size_t</strong> <var>memory_size</var><strong>;</strong> + <strong>cpu_type_t</strong> <var>cpu_type</var><strong>;</strong> + <strong>cpu_subtype_t</strong> <var>cpu_subtype</var><strong>;</strong> + <strong>cpu_threadtype_t</strong> <var>cpu_threadtype</var><strong>;</strong> + <strong>integer_t</strong> <var>physical_cpu</var><strong>;</strong> + <strong>integer_t</strong> <var>physical_cpu_max</var><strong>;</strong> + <strong>integer_t</strong> <var>logical_cpu</var><strong>;</strong> + <strong>integer_t</strong> <var>logical_cpu_max</var><strong>;</strong> + <strong>uint64_t</strong> <var>max_mem</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct host_basic_info* host_basic_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>max_cpus</var> +<dd> +Maximum number of CPUs possible +<p> +<dt> <var>avail_cpus</var> +<dd> +Number of CPUs now available +<p> +<dt> <var>memory_size</var> +<dd> +Size of memory in bytes, capped at 2 GB +<p> +<dt> <var>cpu_type</var> +<dd> +CPU type +<p> +<dt> <var>cpu_subtype</var> +<dd> +CPU sub-type +<p> +<dt> <var>cpu_threadtype</var> +<dd> +CPU thread-type +<p> +<dt> <var>physical_cpu</var> +<dd> +Number of physical CPUs now available +<p> +<dt> <var>physical_cpu_max</var> +<dd> +Maximum number of physical CPUs possible +<p> +<dt> <var>logical_cpu</var> +<dd> +Number of logical CPUs now available +<p> +<dt> <var>logical_cpu_max</var> +<dd> +Maximum number of logical CPUs possible +<p> +<dt> <var>max_mem</var> +<dd> +Actual size of physical memory in bytes +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_basic_info</strong> structure defines the basic information +available about a +host. +<h3>NOTES</h3> +<p> +This structure is machine word length specific because of the memory size +returned. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_info.html"><strong>host_info</strong></a>. +<p> +Data Structures: +<a href="host_load_info.html"><strong>host_load_info</strong></a>, +<a href="host_sched_info.html"><strong>host_sched_info</strong></a>. diff --git a/osfmk/man/host_get_boot_info.html b/osfmk/man/host_get_boot_info.html index e86db863d..3b5c65306 100755 --- a/osfmk/man/host_get_boot_info.html +++ b/osfmk/man/host_get_boot_info.html @@ -1 +1,37 @@ -<h2>host_get_boot_info</h2> <hr> <p> <strong>Function</strong> - Return operator boot information. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_get_boot_info</strong> <strong>(host_priv_t</strong> <var>priv_host</var>, <strong>kernel_boot_info_t</strong> <var>boot_info</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>priv_host</var> <dd> [in host-control send right] The control port for the host for which information is to be obtained. <p> <dt> <var>boot_info</var> <dd> [out array of char] Character string providing the operator boot info </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_get_boot_info</strong> function returns the boot-time information string supplied by the operator when <var>priv_host</var> was initialized. The constant <strong>KERNEL_BOOT_INFO_MAX</strong> (in \*L<mach/host_info.h>\*O) should be used to dimension storage for the returned string. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_info.html"><strong>host_info</strong></a>. \ No newline at end of file +<h2>host_get_boot_info</h2> +<hr> +<p> +<strong>Function</strong> - Return operator boot information. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_get_boot_info</strong> + <strong>(host_priv_t</strong> <var>priv_host</var>, + <strong>kernel_boot_info_t</strong> <var>boot_info</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>priv_host</var> +<dd> +[in host-control send right] +The control port for the host for which +information is to be obtained. +<p> +<dt> <var>boot_info</var> +<dd> +[out array of char] +Character string providing the operator boot info +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_get_boot_info</strong> function returns the boot-time information +string supplied by the operator when <var>priv_host</var> was initialized. +The constant <strong>KERNEL_BOOT_INFO_MAX</strong> (in \*L<mach/host_info.h>\*O) +should be used to dimension storage for the returned string. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_info.html"><strong>host_info</strong></a>. diff --git a/osfmk/man/host_get_clock_control.html b/osfmk/man/host_get_clock_control.html index 4d47043bb..42e1e00a9 100755 --- a/osfmk/man/host_get_clock_control.html +++ b/osfmk/man/host_get_clock_control.html @@ -1 +1,64 @@ -<h2>host_get_clock_control</h2> <hr> <p> <strong>Function</strong> - Return a send right to a kernel clock's control port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_get_clock_control</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>clock_id_t</strong> <var>id</var>, <strong>clock_ctrl_t</strong> <var>clock_control</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control send right] The control port for the host owning the clock. <p> <dt> <var>id</var> <dd> [in scalar] The identification of the desired kernel clock. These values are defined in \*L<mach/clock_types.h>\*O. Although an implementation may define additional values, the following values are always defined (although only the REALTIME clock is required to be implemented): <dl> <p> <dt> <strong>REALTIME_CLOCK</strong> <dd> A moderate resolution clock service that (typically) tracks time since the system last boot. <p> <dt> <strong>BATTERY_CLOCK</strong> <dd> A (typically) low resolution clock (to the second) that survives power failures or service outages. <p> <dt> <strong>HIGHRES_CLOCK</strong> <dd> A high resolution clock. </dl> <p> <dt> <var>clock_control</var> <dd> [out clock-control send right] Control port for the clock. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_get_clock_control</strong> function returns a send right to the control port for a kernel clock object. This right is used to set the clock's resolution and time. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="clock_set_time.html"><strong>clock_set_time</strong></a>, <a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>, <a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>. \ No newline at end of file +<h2>host_get_clock_control</h2> +<hr> +<p> +<strong>Function</strong> - Return a send right to a kernel clock's control port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_get_clock_control</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>clock_id_t</strong> <var>id</var>, + <strong>clock_ctrl_t</strong> <var>clock_control</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The control port for the host owning the +clock. +<p> +<dt> <var>id</var> +<dd> +[in scalar] +The identification of the desired kernel clock. These values +are defined in \*L<mach/clock_types.h>\*O. Although an implementation +may define additional values, the following values are always defined +(although only the REALTIME clock is required to be implemented): +<dl> +<p> +<dt> <strong>REALTIME_CLOCK</strong> +<dd> +A moderate resolution clock service that (typically) tracks +time since the system last boot. +<p> +<dt> <strong>BATTERY_CLOCK</strong> +<dd> +A (typically) low resolution clock (to the second) that +survives power failures or service outages. +<p> +<dt> <strong>HIGHRES_CLOCK</strong> +<dd> +A high resolution clock. +</dl> +<p> +<dt> <var>clock_control</var> +<dd> +[out clock-control send right] +Control port for the clock. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_get_clock_control</strong> function returns a send +right to the control port for +a kernel clock object. This right is used to set the clock's +resolution and time. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="clock_set_time.html"><strong>clock_set_time</strong></a>, +<a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>, +<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>. diff --git a/osfmk/man/host_get_clock_service.html b/osfmk/man/host_get_clock_service.html index b9c9ea09e..9d6b37039 100755 --- a/osfmk/man/host_get_clock_service.html +++ b/osfmk/man/host_get_clock_service.html @@ -1 +1,68 @@ -<h2>host_get_clock_service</h2> <hr> <p> <strong>Function</strong> - Return a send right to a kernel clock's service port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_get_clock_service</strong> <strong>(host_t</strong> <var>host</var>, <strong>clock_id_t</strong> <var>id</var>, <strong>clock_t</strong> <var>clock_name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host</var> <dd> [in host-name send right] The name (or control) port for the host owning the clock. <p> <dt> <var>id</var> <dd> [in scalar] The identification of the desired kernel clock. These values are defined in \*L<mach/clock_types.h>\*O. Although an implementation may define additional values, the following values are always defined (although only the REALTIME clock is required to be implemented): <dl> <p> <dt> <strong>REALTIME_CLOCK</strong> <dd> A moderate resolution clock service that (typically) tracks time since the system last boot. <p> <dt> <strong>BATTERY_CLOCK</strong> <dd> A (typically) low resolution clock (to the second) that survives power failures or service outages. <p> <dt> <strong>HIGHRES_CLOCK</strong> <dd> A high resolution clock. </dl> <p> <dt> <var>clock_name</var> <dd> [out clock-name send right] Name port for the clock. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_get_clock_service</strong> function returns a send right to the name port for a kernel clock object. This right is used to get the time and resolutions of the clock and to set clock alarms. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="clock_get_time.html"><strong>clock_get_time</strong></a>, <a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, <a href="clock_map_time.html"><strong>clock_map_time</strong></a>, <a href="clock_sleep.html"><strong>clock_sleep</strong></a>, <a href="clock_alarm.html"><strong>clock_alarm</strong></a>, <a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>. \ No newline at end of file +<h2>host_get_clock_service</h2> +<hr> +<p> +<strong>Function</strong> - Return a send right to a kernel clock's service port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_get_clock_service</strong> + <strong>(host_t</strong> <var>host</var>, + <strong>clock_id_t</strong> <var>id</var>, + <strong>clock_t</strong> <var>clock_name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host</var> +<dd> +[in host-name send right] +The name (or control) port for the host +owning the clock. +<p> +<dt> <var>id</var> +<dd> +[in scalar] +The identification of the desired kernel clock. These values +are defined in \*L<mach/clock_types.h>\*O. Although an implementation +may define additional values, the following values are always defined +(although only the REALTIME clock is required to be implemented): +<dl> +<p> +<dt> <strong>REALTIME_CLOCK</strong> +<dd> +A moderate resolution clock service that (typically) tracks +time since the system last boot. +<p> +<dt> <strong>BATTERY_CLOCK</strong> +<dd> +A (typically) low resolution clock (to the second) that +survives power failures or service outages. +<p> +<dt> <strong>HIGHRES_CLOCK</strong> +<dd> +A high resolution clock. +</dl> +<p> +<dt> <var>clock_name</var> +<dd> +[out clock-name send right] +Name port for the clock. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_get_clock_service</strong> function returns a send +right to the name port for a +kernel clock object. This right is used to get the time and +resolutions of the +clock and to set clock alarms. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="clock_get_time.html"><strong>clock_get_time</strong></a>, +<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>, +<a href="clock_map_time.html"><strong>clock_map_time</strong></a>, +<a href="clock_sleep.html"><strong>clock_sleep</strong></a>, +<a href="clock_alarm.html"><strong>clock_alarm</strong></a>, +<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>. diff --git a/osfmk/man/host_get_time.html b/osfmk/man/host_get_time.html index 27002bf51..efd1840c1 100755 --- a/osfmk/man/host_get_time.html +++ b/osfmk/man/host_get_time.html @@ -1 +1,38 @@ -<h2>host_get_time</h2> <hr> <p> <strong>Function</strong> - Return the current time. <h3>SYNOPSIS</h3> <pre> <strong>#include< mach/mach_host.h></strong> <strong>kern_return_t host_get_time</strong> <strong>(host_t</strong> <var>host</var>, <strong>time_value_t</strong> <var>current_time</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host</var> <dd> [in host-name port] The name port the host for which the time is to be set. <p> <dt> <var>current_time</var> <dd> [out structure] Returned time value. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_get_time</strong> function returns the current time as seen by that <var>host</var>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_adjust_time.html"><strong>host_adjust_time</strong></a>, <a href="host_set_time.html"><strong>host_set_time</strong></a>. <p> Data Structures: time_value. \ No newline at end of file +<h2>host_get_time</h2> +<hr> +<p> +<strong>Function</strong> - Return the current time. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< mach/mach_host.h></strong> + +<strong>kern_return_t host_get_time</strong> + <strong>(host_t</strong> <var>host</var>, + <strong>time_value_t</strong> <var>current_time</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host</var> +<dd> +[in host-name port] The name port the host for which the time is to be set. +<p> +<dt> <var>current_time</var> +<dd> +[out structure] Returned time value. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_get_time</strong> function returns the current time +as seen by that <var>host</var>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_adjust_time.html"><strong>host_adjust_time</strong></a>, +<a href="host_set_time.html"><strong>host_set_time</strong></a>. +<p> +Data Structures: +time_value. diff --git a/osfmk/man/host_info.html b/osfmk/man/host_info.html index 8bafeb2a4..23a38fdc1 100755 --- a/osfmk/man/host_info.html +++ b/osfmk/man/host_info.html @@ -1 +1,80 @@ -<h2>host_info</h2> <hr> <p> <strong>Function</strong> - Return information about a host. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_info</strong> <strong>(host_t</strong> <var>host</var>, <strong>host_flavor_t</strong> <var>flavor</var>, <strong>host_info_t</strong> <var>host_info</var>, <strong>mach_msg_type_number_t</strong> <var>host_info_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host</var> <dd> [in host-name send right] The name (or control) port for the host for which information is to be obtained. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of statistics desired: <dl> <p> <dt> <strong>HOST_BASIC_INFO</strong> <dd> Basic information (number of processors, amount of memory). The returned structure is <strong>host_basic_info</strong>. <p> <dt> <strong>HOST_SCHED_INFO</strong> <dd> Basic restrictions of the kernel's scheduling, minimum quantum and time-out value. The returned structure is <strong>host_sched_info</strong>. <p> <dt> <strong>HOST_RESOURCE_SIZES</strong> <dd> This interface feature is not implemented in OSF/1 R1.3. Size of significant kernel structures, as a ledger would consider them when limiting kernel resource consumption. The returned structure is <strong>kernel_resource_sizes</strong>. </dl> <p> <dt> <var>host_info</var> <dd> [out structure] Statistics about the specified host. <p> <dt> <var>host_info_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_info</strong> function returns selected information about a host, as specified by <var>flavor</var>. <h3>NOTES</h3> <p> This interface is machine word length specific because of the memory size returned by <strong>HOST_BASIC_INFO</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_get_boot_info.html"><strong>host_get_boot_info</strong></a>, <a href="host_kernel_version.html"><strong>host_kernel_version</strong></a>, <a href="host_statistics.html"><strong>host_statistics</strong></a>. <p> Data Structures: <a href="host_basic_info.html"><strong>host_basic_info</strong></a>, <a href="host_sched_info.html"><strong>host_sched_info</strong></a>, <a href="kernel_resource_sizes.html"><strong>kernel_resource_sizes</strong></a>. \ No newline at end of file +<h2>host_info</h2> +<hr> +<p> +<strong>Function</strong> - Return information about a host. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_info</strong> + <strong>(host_t</strong> <var>host</var>, + <strong>host_flavor_t</strong> <var>flavor</var>, + <strong>host_info_t</strong> <var>host_info</var>, + <strong>mach_msg_type_number_t</strong> <var>host_info_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host</var> +<dd> +[in host-name send right] +The name (or control) port for the host for +which information is to be obtained. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of statistics desired: +<dl> +<p> +<dt> <strong>HOST_BASIC_INFO</strong> +<dd> +Basic information (number of processors, amount of +memory). The returned structure is <strong>host_basic_info</strong>. +<p> +<dt> <strong>HOST_SCHED_INFO</strong> +<dd> +Basic restrictions of the kernel's scheduling, minimum +quantum and time-out value. The returned structure is +<strong>host_sched_info</strong>. +<p> +<dt> <strong>HOST_RESOURCE_SIZES</strong> +<dd> +This interface feature is not implemented in OSF/1 R1.3. +Size of significant kernel structures, as a ledger would +consider them when limiting kernel resource consumption. The +returned structure is <strong>kernel_resource_sizes</strong>. +</dl> +<p> +<dt> <var>host_info</var> +<dd> +[out structure] +Statistics about the specified host. +<p> +<dt> <var>host_info_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_info</strong> function returns selected information +about a host, as specified +by <var>flavor</var>. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the memory size +returned by <strong>HOST_BASIC_INFO</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_get_boot_info.html"><strong>host_get_boot_info</strong></a>, +<a href="host_kernel_version.html"><strong>host_kernel_version</strong></a>, +<a href="host_statistics.html"><strong>host_statistics</strong></a>. +<p> +Data Structures: +<a href="host_basic_info.html"><strong>host_basic_info</strong></a>, +<a href="host_sched_info.html"><strong>host_sched_info</strong></a>, +<a href="kernel_resource_sizes.html"><strong>kernel_resource_sizes</strong></a>. diff --git a/osfmk/man/host_kernel_version.html b/osfmk/man/host_kernel_version.html index 00d7f9e46..cd8ad1607 100755 --- a/osfmk/man/host_kernel_version.html +++ b/osfmk/man/host_kernel_version.html @@ -1 +1,41 @@ -<h2>host_kernel_version</h2> <hr> <p> <strong>Function</strong> - Return kernel version information for a host. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_kernel_version</strong> <strong>(host_t</strong> <var>host</var>, <strong>kernel_version_t</strong> <var>version</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host</var> <dd> [in host-name send right] The name (or control) port for the host for which information is to be obtained. <p> <dt> <var>version</var> <dd> [out array of <var>char</var>] Character string describing the kernel version executing on <var>host</var>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_kernel_version</strong> function returns the version string compiled into the kernel executing on <var>host</var> at the time it was built. This describes the version of the kernel. The constant <strong>KERNEL_VERSION_MAX</strong> (in \*L<mach/host_info.h>\*O) should be used to dimension storage for the returned string if the <var>kernel_version_t</var> declaration is not used. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_info.html"><strong>host_info</strong></a>. \ No newline at end of file +<h2>host_kernel_version</h2> +<hr> +<p> +<strong>Function</strong> - Return kernel version information for a host. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_kernel_version</strong> + <strong>(host_t</strong> <var>host</var>, + <strong>kernel_version_t</strong> <var>version</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host</var> +<dd> +[in host-name send right] +The name (or control) port for the host for +which information is to be obtained. +<p> +<dt> <var>version</var> +<dd> +[out array of <var>char</var>] +Character string describing the kernel version +executing on <var>host</var>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_kernel_version</strong> function returns the version +string compiled into the +kernel executing on <var>host</var> at the time it was built. This describes +the version of the kernel. The constant <strong>KERNEL_VERSION_MAX</strong> (in +\*L<mach/host_info.h>\*O) +should be used to dimension storage for the returned string if the +<var>kernel_version_t</var> declaration is not used. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_info.html"><strong>host_info</strong></a>. diff --git a/osfmk/man/host_load_info.html b/osfmk/man/host_load_info.html index ab61fa27b..4a851f39c 100755 --- a/osfmk/man/host_load_info.html +++ b/osfmk/man/host_load_info.html @@ -1 +1,47 @@ -<h2>host_load_info</h2> <hr> <p> <strong>Structure</strong> - Used to present a host's processor load information. <h3>SYNOPSIS</h3> <pre> <strong>#define CPU_STATE_USER 0</strong> <strong>#define CPU_STATE_SYSTEM 1</strong> <strong>#define CPU_STATE_IDLE 2</strong> <strong>struct host_load_info</strong> <strong>{</strong> <strong>integer_t</strong> <var>avenrun</var><strong>[3];</strong> <strong>integer_t</strong> <var>mach_factor</var><strong>[3];</strong> <strong>};</strong> <strong>typedef struct host_load_info* host_load_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>avenrun</var> <dd> load average--average number of runnable processes divided by number of CPUs <p> <dt> <var>mach_factor</var> <dd> The processing resources available to a new thread--the number of CPUs divided by (1 + the number of threads) </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_load_info</strong> structure defines the loading information available about a host. The information returned is exponential averages over three periods of time: 5, 30 and 60 seconds. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_statistics.html"><strong>host_statistics</strong></a>. <p> Data Structures: <a href="host_basic_info.html"><strong>host_basic_info</strong></a>, <a href="host_sched_info.html"><strong>host_sched_info</strong></a>. \ No newline at end of file +<h2>host_load_info</h2> +<hr> +<p> +<strong>Structure</strong> - Used to present a host's processor load information. +<h3>SYNOPSIS</h3> +<pre> +<strong>#define CPU_STATE_USER 0</strong> + +<strong>#define CPU_STATE_SYSTEM 1</strong> + +<strong>#define CPU_STATE_IDLE 2</strong> + +<strong>struct host_load_info</strong> +<strong>{</strong> + <strong>integer_t</strong> <var>avenrun</var><strong>[3];</strong> + <strong>integer_t</strong> <var>mach_factor</var><strong>[3];</strong> +<strong>};</strong> + +<strong>typedef struct host_load_info* host_load_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>avenrun</var> +<dd> +load average--average number of runnable processes divided by +number of CPUs +<p> +<dt> <var>mach_factor</var> +<dd> +The processing resources available to a new thread--the number of +CPUs divided by (1 + the number of threads) +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_load_info</strong> structure defines the loading information +available about a +host. The information returned is exponential averages over three periods of +time: 5, 30 and 60 seconds. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_statistics.html"><strong>host_statistics</strong></a>. +<p> +Data Structures: +<a href="host_basic_info.html"><strong>host_basic_info</strong></a>, +<a href="host_sched_info.html"><strong>host_sched_info</strong></a>. + diff --git a/osfmk/man/host_page_size.html b/osfmk/man/host_page_size.html index 38fca4546..9472c2094 100755 --- a/osfmk/man/host_page_size.html +++ b/osfmk/man/host_page_size.html @@ -1 +1,34 @@ -<h2>host_page_size</h2> <hr> <p> <strong>Function</strong> - Provide the system's virtual page size. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_page_size</strong> <strong>(host_t</strong> <var>host</var>, <strong>vm_size_t</strong> <var>page_size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host</var> <dd> [in host-name send right] The name (or control) port for the host for which the page size is desired. <p> <dt> <var>page_size</var> <dd> [out scalar] The host's page size (in bytes). </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_page_size</strong> function returns the page size for the given host. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_host_self.html"><strong>mach_host_self</strong></a>. \ No newline at end of file +<h2>host_page_size</h2> +<hr> +<p> +<strong>Function</strong> - Provide the system's virtual page size. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_page_size</strong> + <strong>(host_t</strong> <var>host</var>, + <strong>vm_size_t</strong> <var>page_size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host</var> +<dd> +[in host-name send right] +The name (or control) port for the host for +which the page size is desired. +<p> +<dt> <var>page_size</var> +<dd> +[out scalar] +The host's page size (in bytes). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_page_size</strong> function returns the page size for the given host. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_host_self.html"><strong>mach_host_self</strong></a>. diff --git a/osfmk/man/host_processor_set_priv.html b/osfmk/man/host_processor_set_priv.html index c8ec25271..bb5375ba2 100755 --- a/osfmk/man/host_processor_set_priv.html +++ b/osfmk/man/host_processor_set_priv.html @@ -1 +1,48 @@ -<h2>host_processor_set_priv</h2> <hr> <p> <strong>Function</strong> - Translate a processor set name port into a processor set control port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_processor_set_priv</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>processor_set_name_t</strong> <var>set_name</var>, <strong>processor_set_t</strong> <var>processor_set</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control send right] The control port for the host for which the processor set is desired. <p> <dt> <var>set_name</var> <dd> [in processor-set-name send right] The name port for the processor set desired. <p> <dt> <var>processor_set</var> <dd> [out processor-set-control send right] The returned processor set control port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_processor_set_priv</strong> function returns send rights for the control port for a specified processor set currently existing on <var>host_priv</var>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_processor_sets.html"><strong>host_processor_sets</strong></a>, <a href="processor_set_create.html"><strong>processor_set_create</strong></a>, <a href="processor_set_tasks.html"><strong>processor_set_tasks</strong></a>, <a href="processor_set_threads.html"><strong>processor_set_threads</strong></a>. \ No newline at end of file +<h2>host_processor_set_priv</h2> +<hr> +<p> +<strong>Function</strong> - Translate a processor set name port + into a processor set control port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_processor_set_priv</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>processor_set_name_t</strong> <var>set_name</var>, + <strong>processor_set_t</strong> <var>processor_set</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The control port for the host for which the +processor set is desired. +<p> +<dt> <var>set_name</var> +<dd> +[in processor-set-name send right] +The name port for the processor set +desired. +<p> +<dt> <var>processor_set</var> +<dd> +[out processor-set-control send right] +The returned processor set +control port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_processor_set_priv</strong> function returns send rights +for the control port +for a specified processor set currently existing on <var>host_priv</var>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_processor_sets.html"><strong>host_processor_sets</strong></a>, +<a href="processor_set_create.html"><strong>processor_set_create</strong></a>, +<a href="processor_set_tasks.html"><strong>processor_set_tasks</strong></a>, +<a href="processor_set_threads.html"><strong>processor_set_threads</strong></a>. diff --git a/osfmk/man/host_processor_sets.html b/osfmk/man/host_processor_sets.html index 41811d358..91bb9356c 100755 --- a/osfmk/man/host_processor_sets.html +++ b/osfmk/man/host_processor_sets.html @@ -1 +1,52 @@ -<h2>host_processor_sets</h2> <hr> <p> <strong>Function</strong> - Return a list of send rights representing all processor set name ports. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_processor_sets</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>processor_set_name_port_array_t</strong><var>processor_set_name_list</var>, <strong>host_priv</strong> <var>processor_set_name_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control send right] The control port for the host for which the processor sets are desired. <p> <dt> <var>processor_set_name_list</var> <dd> [out pointer to dynamic array of processor-set-name send rights] The set of processor set name ports for those currently existing on <var>host_priv</var>; no particular order is guaranteed. <p> <dt> <var>processor_set_name_count</var> <dd> [out scalar] The number of processor set names returned. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_processor_sets</strong> function returns send rights for the name ports for each processor set currently existing on host. <h3>NOTES</h3> <p> If control ports to the processor sets are needed, use <strong>host_processor_set_priv</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_processor_set_priv.html"><strong>host_processor_set_priv</strong></a>, <a href="processor_set_create.html"><strong>processor_set_create</strong></a>, <a href="processor_set_tasks.html"><strong>processor_set_tasks</strong></a>, <a href="processor_set_threads.html"><strong>processor_set_threads</strong></a>. \ No newline at end of file +<h2>host_processor_sets</h2> +<hr> +<p> +<strong>Function</strong> - Return a list of send rights representing all processor set name ports. + +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_processor_sets</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>processor_set_name_port_array_t</strong><var>processor_set_name_list</var>, + <strong>host_priv</strong> <var>processor_set_name_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The control port for the host for which the +processor sets are desired. +<p> +<dt> <var>processor_set_name_list</var> +<dd> +[out pointer to dynamic array of processor-set-name send rights] +The +set of processor set name ports for those currently existing on +<var>host_priv</var>; no particular order is guaranteed. +<p> +<dt> <var>processor_set_name_count</var> +<dd> +[out scalar] +The number of processor set names returned. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_processor_sets</strong> function returns send rights +for the name ports for +each processor set currently existing on host. +<h3>NOTES</h3> +<p> +If control ports to the processor sets are needed, use +<strong>host_processor_set_priv</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_processor_set_priv.html"><strong>host_processor_set_priv</strong></a>, +<a href="processor_set_create.html"><strong>processor_set_create</strong></a>, +<a href="processor_set_tasks.html"><strong>processor_set_tasks</strong></a>, +<a href="processor_set_threads.html"><strong>processor_set_threads</strong></a>. diff --git a/osfmk/man/host_processor_slots.html b/osfmk/man/host_processor_slots.html index 89ec2a170..f2013fc84 100755 --- a/osfmk/man/host_processor_slots.html +++ b/osfmk/man/host_processor_slots.html @@ -1 +1,46 @@ -<h2>host_processor_slots</h2> <hr> <p> <strong>Function</strong> - Return a list of numbers that map processor slots to active processors. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_processor_slots</strong> <strong>(host_t</strong> <var>host</var>, <strong>processor_slot_t</strong> <var>slots</var>, <strong>host</strong> <var>count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host</var> <dd> [in host-name send right] The name (or control) port for the host for which information is to be obtained. <p> <dt> <var>slots</var> <dd> [out array of <var>processor_slot_t</var>] An array of the processor slot numbers for active processors. <p> <dt> <var>count</var> <dd> [pointer to in/out scalar] On input, the maximum size of the slots buffer; on output, the number of returned slot numbers. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_processor_slots</strong> function returns an array of the processor slots defined for the host. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_info.html"><strong>host_info</strong></a>, <a href="host_processors.html"><strong>host_processors</strong></a>, <a href="processor_info.html"><strong>processor_info</strong></a>. \ No newline at end of file +<h2>host_processor_slots</h2> +<hr> +<p> +<strong>Function</strong> - Return a list of numbers that map processor slots to active processors. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_processor_slots</strong> + <strong>(host_t</strong> <var>host</var>, + <strong>processor_slot_t</strong> <var>slots</var>, + <strong>host</strong> <var>count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host</var> +<dd> +[in host-name send right] +The name (or control) port for the host for +which information is to be obtained. +<p> +<dt> <var>slots</var> +<dd> +[out array of <var>processor_slot_t</var>] +An array of the processor slot numbers +for active processors. +<p> +<dt> <var>count</var> +<dd> +[pointer to in/out scalar] +On input, the maximum size of the slots +buffer; on output, the number of returned slot numbers. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_processor_slots</strong> function returns an array +of the processor slots +defined for the host. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_info.html"><strong>host_info</strong></a>, +<a href="host_processors.html"><strong>host_processors</strong></a>, +<a href="processor_info.html"><strong>processor_info</strong></a>. diff --git a/osfmk/man/host_processors.html b/osfmk/man/host_processors.html index 4f0d57a13..bd7c77baa 100755 --- a/osfmk/man/host_processors.html +++ b/osfmk/man/host_processors.html @@ -1 +1,46 @@ -<h2>host_processors</h2> <hr> <p> <strong>Function</strong> - Return a list of send rights representing all processor ports. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_processors</strong> <strong>(host_t</strong> <var>host_priv</var>, <strong>processor_port_array_t</strong> <var>processor_list</var>, <strong>host_priv</strong> <var>processor_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control send right] The control port for the desired host. <p> <dt> <var>processor_list</var> <dd> [out pointer to dynamic array of processor send rights] The set of processors existing on <var>host_priv</var>; no particular order is guaranteed. <p> <dt> <var>processor_count</var> <dd> [out scalar] The number of ports returned in <var>processor_list</var>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_processors</strong> function returns an array of send right ports for each processor existing on <var>host_priv</var>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_start.html"><strong>processor_start</strong></a>, <a href="processor_exit.html"><strong>processor_exit</strong></a>, <a href="processor_info.html"><strong>processor_info</strong></a>, <a href="processor_control.html"><strong>processor_control</strong></a>, <a href="host_processor_slots.html"><strong>host_processor_slots</strong></a>. \ No newline at end of file +<h2>host_processors</h2> +<hr> +<p> +<strong>Function</strong> - Return a list of send rights representing all processor ports. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_processors</strong> + <strong>(host_t</strong> <var>host_priv</var>, + <strong>processor_port_array_t</strong> <var>processor_list</var>, + <strong>host_priv</strong> <var>processor_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The control port for the desired host. +<p> +<dt> <var>processor_list</var> +<dd> +[out pointer to dynamic array of processor send rights] +The set of +processors existing on <var>host_priv</var>; no particular order is guaranteed. +<p> +<dt> <var>processor_count</var> +<dd> +[out scalar] +The number of ports returned in <var>processor_list</var>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_processors</strong> function returns an array of send +right ports for each +processor existing on <var>host_priv</var>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_start.html"><strong>processor_start</strong></a>, +<a href="processor_exit.html"><strong>processor_exit</strong></a>, +<a href="processor_info.html"><strong>processor_info</strong></a>, +<a href="processor_control.html"><strong>processor_control</strong></a>, +<a href="host_processor_slots.html"><strong>host_processor_slots</strong></a>. diff --git a/osfmk/man/host_reboot.html b/osfmk/man/host_reboot.html index 7a7fa6159..db320557a 100755 --- a/osfmk/man/host_reboot.html +++ b/osfmk/man/host_reboot.html @@ -1 +1,35 @@ -<h2>host_reboot</h2> <hr> <p> <strong>Function</strong> - Reboot this host. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_reboot</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>int</strong> <var>options</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control send right] The control port the host to be re-booted. <p> <dt> <var>options</var> <dd> [in scalar] Reboot options. See \*L<mach/host_reboot.h>\*O for details. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_reboot</strong> function reboots the specified host. <h3>NOTES</h3> <p> If successful, this call will not return. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> None. \ No newline at end of file +<h2>host_reboot</h2> +<hr> +<p> +<strong>Function</strong> - Reboot this host. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_reboot</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>int</strong> <var>options</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The control port the host to be re-booted. +<p> +<dt> <var>options</var> +<dd> +[in scalar] +Reboot options. See \*L<mach/host_reboot.h>\*O for details. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_reboot</strong> function reboots the specified host. +<h3>NOTES</h3> +<p> +If successful, this call will not return. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +None. diff --git a/osfmk/man/host_sched_info.html b/osfmk/man/host_sched_info.html index 581af5261..4cdbc4d98 100755 --- a/osfmk/man/host_sched_info.html +++ b/osfmk/man/host_sched_info.html @@ -1 +1,39 @@ -<h2>host_sched_info</h2> <hr> <p> <strong>Structure</strong> - Used to present the set of scheduler limits associated with the host. <h3>SYNOPSIS</h3> <pre> <strong>struct host_sched_info</strong> <strong>{</strong> <strong>integer_t</strong> <var>min_timeout</var><strong>;</strong> <strong>integer_t</strong> <var>min_quantum</var><strong>;</strong> <strong>};</strong> <strong>typedef struct host_sched_info* host_sched_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>min_timeout</var> <dd> Minimum time-out, in milliseconds <p> <dt> <var>min_quantum</var> <dd> Minimum quantum (period for which a thread can be scheduled if uninterrupted), in milliseconds </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_sched_info</strong> structure defines the limiting scheduling information available about a host. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_info.html"><strong>host_info</strong></a>. <p> Data Structures: <a href="host_basic_info.html"><strong>host_basic_info</strong></a>, <a href="host_load_info.html"><strong>host_load_info</strong></a>. \ No newline at end of file +<h2>host_sched_info</h2> +<hr> +<p> +<strong>Structure</strong> - Used to present the set of scheduler limits associated + with the host. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct host_sched_info</strong> +<strong>{</strong> + <strong>integer_t</strong> <var>min_timeout</var><strong>;</strong> + <strong>integer_t</strong> <var>min_quantum</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct host_sched_info* host_sched_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>min_timeout</var> +<dd> +Minimum time-out, in milliseconds +<p> +<dt> <var>min_quantum</var> +<dd> +Minimum quantum (period for which a thread can be scheduled if +uninterrupted), in milliseconds +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_sched_info</strong> structure defines the limiting +scheduling information +available about a host. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_info.html"><strong>host_info</strong></a>. +<p> +Data Structures: +<a href="host_basic_info.html"><strong>host_basic_info</strong></a>, +<a href="host_load_info.html"><strong>host_load_info</strong></a>. diff --git a/osfmk/man/host_security_create_task_token.html b/osfmk/man/host_security_create_task_token.html index 9fdd8a2b2..290f40319 100755 --- a/osfmk/man/host_security_create_task_token.html +++ b/osfmk/man/host_security_create_task_token.html @@ -1 +1,73 @@ -<h2>host_security_create_task_token</h2> <hr> <p> <strong>Function</strong> - Create a new task with an explicit security token. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_security_create_task_token</strong> <strong>(host_security_t</strong> <var>host_security</var>, <strong>task_t</strong> <var>parent_task</var>, <strong>security_token_t</strong> <var>security_token</var>, <strong>audit_token_t</strong> <var>audit_token</var>, <strong>ledger_port_array_t</strong> <var>ledgers</var>, <strong>boolean_t</strong> <var>inherit_memory</var>, <strong>task_t</strong> <var>child_task</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt><var>host_security</var> <dd> [in security send right] The host's security port. <p> <dt><var>parent_task</var> <dd> [in task send right] The port for the task from which to draw the child task's port rights and address space. <p> <dt><var>security_token</var> <dd> [in scalar] The task's security token. <p> <dt><var>audit_token</var> <dd> [in scalar] The task's audit token. <p> <dt><var>ledgers</var> <dd> [pointer to in array of ledger send rights] The set of ledgers from which the task will draw its resources. <p> <dt><var>inherit_memory</var> <dd> [in scalar] Address space inheritance indicator. If true, the child task in- herits the address space of the parent task. If false, the kernel assigns the child task an empty address space. <p> <dt><var>child_task</var> <dd> [out task send right] The kernel-assigned port name for the new task. </dl> <h3>DESCRIPTION</h3> <p> The <strong><strong>host_security_create_task_token</strong> function creates a new task from <var>parent_task</var> with explicit security and audit token values, returning the name of the new task in the parameter specified by <var>child_task</var>. Other than the security and audit token values, the child task is as if created by <strong>task_create</strong>. <h3>NOTES</h3> <p> The host security port is a privileged port given to the system bootstrap task for the use of this call. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_SECURITY</strong> <dd> The value of <var>host_security</var> does not specify the security port for the host on which task lies. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="host_security_set_task_token.html"><strong>host_security_set_task_token</strong></a>, <a href="mach_msg.html"><strong>mach_msg</strong></a>. \ No newline at end of file +<h2>host_security_create_task_token</h2> +<hr> +<p> +<strong>Function</strong> - Create a new task with an explicit security token. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_security_create_task_token</strong> + <strong>(host_security_t</strong> <var>host_security</var>, + <strong>task_t</strong> <var>parent_task</var>, + <strong>security_token_t</strong> <var>security_token</var>, + <strong>audit_token_t</strong> <var>audit_token</var>, + <strong>ledger_port_array_t</strong> <var>ledgers</var>, + <strong>boolean_t</strong> <var>inherit_memory</var>, + <strong>task_t</strong> <var>child_task</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt><var>host_security</var> +<dd> +[in security send right] The host's security port. +<p> +<dt><var>parent_task</var> +<dd> +[in task send right] The port for the task from which to draw the child +task's port rights and address space. +<p> +<dt><var>security_token</var> +<dd> +[in scalar] The task's security token. +<p> +<dt><var>audit_token</var> +<dd> +[in scalar] The task's audit token. +<p> +<dt><var>ledgers</var> +<dd> +[pointer to in array of ledger send rights] The set of ledgers from which the +task will draw its resources. +<p> +<dt><var>inherit_memory</var> +<dd> +[in scalar] Address space inheritance indicator. If true, the child task in- +herits the address space of the parent task. If false, the kernel assigns +the child task an empty address space. +<p> +<dt><var>child_task</var> +<dd> +[out task send right] The kernel-assigned port name for the new task. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong><strong>host_security_create_task_token</strong> function creates a new task from +<var>parent_task</var> with explicit security and audit token values, returning the name of the +new task in the parameter specified by <var>child_task</var>. Other than the security and audit token values, the child task +is as if created by <strong>task_create</strong>. +<h3>NOTES</h3> +<p> +The host security port is a privileged port given to the system +bootstrap task for the use of this call. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_SECURITY</strong> +<dd> +The value of <var>host_security</var> does not specify the security port for the host on which task lies. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="host_security_set_task_token.html"><strong>host_security_set_task_token</strong></a>, +<a href="mach_msg.html"><strong>mach_msg</strong></a>. diff --git a/osfmk/man/host_security_set_task_token.html b/osfmk/man/host_security_set_task_token.html index 052694e55..0c58dcd06 100755 --- a/osfmk/man/host_security_set_task_token.html +++ b/osfmk/man/host_security_set_task_token.html @@ -1 +1,60 @@ -<h2>host_security_set_task_token</h2> <hr> <p> <strong>Function</strong> - Change the target task's security token. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_security_set_task_token</strong> <strong>(host_security_t</strong> <var>host_security</var>, <strong>task_t</strong> <var>task</var>, <strong>security_token_t</strong> <var>security_token</var>, <strong>audit_token_t</strong> <var>audit_token</var>, <strong>host_t</strong> <var>host</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt><var>host_security</var> <dd> [in security send right] The host's security port. <p> <dt><var>task</var> <dd> [in task send right] The port for the task for which the token is to be set. <p> <dt><var>security_token</var> <dd> [in scalar] The new security token. <p> <dt><var>audit_token</var> <dd> [in scalar] The new audit token. <p> <dt><var>host</var> <dd> [in host send right] The task's new host-self port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_security_set_task_token</strong> function changes the specified task's security and audit tokens; the new tokens will be included in all subsequent messages sent from the task. The initial value of a task's security and audit tokens is that of its parent. <h3>NOTES</h3> <p> The host security port is a privileged port given to the system bootstrap task for the use of this call. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_SECURITY</strong> <dd> The value of <var>host_security</var> does not specify the security port for the host on which task lies. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="task_info.html"><strong>task_info</strong></a>, <a href="mach_msg.html"><strong>mach_msg</strong></a>. \ No newline at end of file +<h2>host_security_set_task_token</h2> +<hr> +<p> +<strong>Function</strong> - Change the target task's security token. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_security_set_task_token</strong> + <strong>(host_security_t</strong> <var>host_security</var>, + <strong>task_t</strong> <var>task</var>, + <strong>security_token_t</strong> <var>security_token</var>, + <strong>audit_token_t</strong> <var>audit_token</var>, + <strong>host_t</strong> <var>host</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt><var>host_security</var> +<dd> +[in security send right] The host's security port. +<p> +<dt><var>task</var> +<dd> +[in task send right] The port for the task for which the token is to be set. +<p> +<dt><var>security_token</var> +<dd> +[in scalar] The new security token. +<p> +<dt><var>audit_token</var> +<dd> +[in scalar] The new audit token. +<p> +<dt><var>host</var> +<dd> +[in host send right] The task's new host-self port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_security_set_task_token</strong> function changes the +specified task's security and audit tokens; the new tokens will be +included in all subsequent messages sent from the task. The +initial value of a task's security and audit tokens is that of its +parent. +<h3>NOTES</h3> +<p> +The host security port is a privileged port given to the system +bootstrap task for the use of this call. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_SECURITY</strong> +<dd> +The value of <var>host_security</var> does not specify the security port for the host on which task lies. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="mach_msg.html"><strong>mach_msg</strong></a>. diff --git a/osfmk/man/host_set_time.html b/osfmk/man/host_set_time.html index cbe6cf580..45ad2019a 100755 --- a/osfmk/man/host_set_time.html +++ b/osfmk/man/host_set_time.html @@ -1 +1,37 @@ -<h2>host_set_time</h2> <hr> <p> <strong>Function</strong> - Sets the time. <h3>SYNOPSIS</h3> <pre> <strong>#include< mach/mach_host.h></strong> <strong>kern_return_t host_set_time</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>time_value_t</strong> <var>new_time</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control port] The control port for the host for which the time is to be set. <p> <dt> <var>new_time</var> <dd> [in structure] Time to be set. </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_set_time</strong> function establishes the time on the specified host. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_adjust_time.html"><strong>host_adjust_time</strong></a>, <a href="host_get_time.html"><strong>host_get_time</strong></a>. <p> Data Structures: time_value. \ No newline at end of file +<h2>host_set_time</h2> +<hr> +<p> +<strong>Function</strong> - Sets the time. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< mach/mach_host.h></strong> + +<strong>kern_return_t host_set_time</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>time_value_t</strong> <var>new_time</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control port] The control port for the host for which the time is to be set. +<p> +<dt> <var>new_time</var> +<dd> +[in structure] Time to be set. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_set_time</strong> function establishes the time on the specified host. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_adjust_time.html"><strong>host_adjust_time</strong></a>, +<a href="host_get_time.html"><strong>host_get_time</strong></a>. +<p> +Data Structures: +time_value. diff --git a/osfmk/man/host_statistics.html b/osfmk/man/host_statistics.html index 45ba471aa..2a79cfc48 100755 --- a/osfmk/man/host_statistics.html +++ b/osfmk/man/host_statistics.html @@ -1 +1,65 @@ -<h2>host_statistics</h2> <hr> <p> <strong>Function</strong> - Return statistics for a host.<h3>SYNOPSIS</h3> <pre> <strong>kern_return_t host_statistics</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>host_flavor_t</strong> <var>flavor</var>, <strong>host_info_t</strong> <var>host_info</var>, <strong>mach_msg_type_number_t</strong> <var>host_info_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control send right] The control port for the host for which information is to be obtained. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of statistics desired. <dl> <p> <dt> <strong>HOST_LOAD_INFO</strong> <dd> System loading statistics. The returned structure is <strong>host_load_info</strong>. <p> <dt> <strong>HOST_VM_INFO</strong> <dd> Virtual memory statistics. The returned structure is <strong>vm_statistics</strong>. </dl> <p> <dt> <var>host_info</var> <dd> [out structure] Statistics about the specified host. <p> <dt> <var>host_info_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>host_statistics</strong> function returns scheduling and virtual memory statistics concerning the host as specified by <var>flavor</var>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_info.html"><strong>host_info</strong></a>, <a href="processor_set_statistics.html"><strong>processor_set_statistics</strong></a>. <p> Data Structures: <a href="host_load_info.html"><strong>host_load_info</strong></a>, <a href="vm_statistics.html"><strong>vm_statistics</strong></a>. \ No newline at end of file +<h2>host_statistics</h2> +<hr> +<p> +<strong>Function</strong> - Return statistics for a host.<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t host_statistics</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>host_flavor_t</strong> <var>flavor</var>, + <strong>host_info_t</strong> <var>host_info</var>, + <strong>mach_msg_type_number_t</strong> <var>host_info_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The control port for the host for which +information is to be obtained. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of statistics desired. +<dl> +<p> +<dt> <strong>HOST_LOAD_INFO</strong> +<dd> +System loading statistics. The returned structure is +<strong>host_load_info</strong>. +<p> +<dt> <strong>HOST_VM_INFO</strong> +<dd> +Virtual memory statistics. The returned structure is +<strong>vm_statistics</strong>. +</dl> +<p> +<dt> <var>host_info</var> +<dd> +[out structure] +Statistics about the specified host. +<p> +<dt> <var>host_info_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>host_statistics</strong> function returns scheduling and +virtual memory statistics +concerning the host as specified by <var>flavor</var>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_info.html"><strong>host_info</strong></a>, +<a href="processor_set_statistics.html"><strong>processor_set_statistics</strong></a>. +<p> +Data Structures: +<a href="host_load_info.html"><strong>host_load_info</strong></a>, +<a href="vm_statistics.html"><strong>vm_statistics</strong></a>. diff --git a/osfmk/man/i386_get_ldt.html b/osfmk/man/i386_get_ldt.html index a00080de0..9f09da6a7 100755 --- a/osfmk/man/i386_get_ldt.html +++ b/osfmk/man/i386_get_ldt.html @@ -1 +1,49 @@ -<h2>i386_get_ldt</h2> <hr> <p> <strong>Function</strong> - Return per-thread segment descriptors. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t i386_get_ldt</strong> <strong>(thread_act_t</strong> <var>target_act</var>, <strong>int</strong> <var>first_selector</var>, <strong>int</strong> <var>desired_count</var>, <strong>descriptor_list_t</strong> <var>desc_list</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_act</var> <dd> [in thread send right] Thread whose segment descriptors are to be returned. <p> <dt> <var>first_selector</var> <dd> [in scalar] Selector value (segment register value) corresponding to the first segment whose descriptor is to be returned. <p> <dt> <var>desired_count</var> <dd> [in scalar] Number of returned descriptors desired. <p> <dt> <var>desc_list</var> <dd> [out pointer to dynamic array of <strong>descriptor_t</strong>] Array of segment descriptors. </dl> <h3>DESCRIPTION</h3> <p> The <strong>i386_get_ldt</strong> function returns per-thread segment descriptors from the thread's local descriptor table (LDT). <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="i386_set_ldt.html"><strong>i386_set_ldt<strong></a>. \ No newline at end of file +<h2>i386_get_ldt</h2> +<hr> +<p> +<strong>Function</strong> - Return per-thread segment descriptors. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t i386_get_ldt</strong> + <strong>(thread_act_t</strong> <var>target_act</var>, + <strong>int</strong> <var>first_selector</var>, + <strong>int</strong> <var>desired_count</var>, + <strong>descriptor_list_t</strong> <var>desc_list</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_act</var> +<dd> +[in thread send right] +Thread whose segment descriptors are to be +returned. +<p> +<dt> <var>first_selector</var> +<dd> +[in scalar] Selector value (segment register value) corresponding to the +first segment whose descriptor is to be returned. +<p> +<dt> <var>desired_count</var> +<dd> +[in scalar] +Number of returned descriptors desired. +<p> +<dt> <var>desc_list</var> +<dd> +[out pointer to dynamic array of <strong>descriptor_t</strong>] +Array of segment +descriptors. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>i386_get_ldt</strong> function returns per-thread segment +descriptors from the +thread's local descriptor table (LDT). +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="i386_set_ldt.html"><strong>i386_set_ldt<strong></a>. diff --git a/osfmk/man/i386_io_port_add.html b/osfmk/man/i386_io_port_add.html index 241c4d872..a65d732b3 100755 --- a/osfmk/man/i386_io_port_add.html +++ b/osfmk/man/i386_io_port_add.html @@ -1 +1,46 @@ -<h2>i386_io_port_add</h2> <hr> <p> <strong>Function</strong> - Permit target thread to invoke operations on the specified device. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t i386_io_port_add</strong> <strong>(thread_act_t</strong> <var>target_act</var>, <strong>device_t</strong> <var>device</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_act</var> <dd> [in thread send right] Thread whose permission bitmap is to be set. <p> <dt> <var>device</var> <dd> [in device send right] The device to which I/O instructions are to be permitted. </dl> <h3>DESCRIPTION</h3> <p> The <strong>i386_io_port_add</strong> function adds a device to the I/O permission bitmap for a thread, thereby permitting the thread to execute I/O instructions against the device. <h3>NOTES</h3> <p> Normally, the thread must have called <strong>i386_io_port_add</strong> for all devices to which it will execute I/O instructions. However, possessing send rights to the <var>iopl</var> device port will cause the <var>iopl</var> device to be automatically added to the thread's I/O map upon first attempted access. This is a backward compatibility feature for the DOS emulator. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="i386_io_port_list.html"><strong>i386_io_port_list<strong></a>, <a href="i386_io_port_remove.html"><strong>i386_io_port_remove<strong></a>. \ No newline at end of file +<h2>i386_io_port_add</h2> +<hr> +<p> +<strong>Function</strong> - Permit target thread to invoke operations on the specified device. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t i386_io_port_add</strong> + <strong>(thread_act_t</strong> <var>target_act</var>, + <strong>device_t</strong> <var>device</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_act</var> +<dd> +[in thread send right] +Thread whose permission bitmap is to be set. +<p> +<dt> <var>device</var> +<dd> +[in device send right] +The device to which I/O instructions are to be +permitted. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>i386_io_port_add</strong> function adds a device to the +I/O permission bitmap for a +thread, thereby permitting the thread to execute I/O instructions against the +device. +<h3>NOTES</h3> +<p> +Normally, the thread must have called <strong>i386_io_port_add</strong> +for all devices to which it will execute I/O instructions. However, possessing +send rights to the <var>iopl</var> device port will cause the +<var>iopl</var> device to be automatically added to the +thread's I/O map upon first attempted access. This is a backward +compatibility feature for the DOS emulator. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="i386_io_port_list.html"><strong>i386_io_port_list<strong></a>, +<a href="i386_io_port_remove.html"><strong>i386_io_port_remove<strong></a>. diff --git a/osfmk/man/i386_io_port_list.html b/osfmk/man/i386_io_port_list.html index 304aca085..295baffaf 100755 --- a/osfmk/man/i386_io_port_list.html +++ b/osfmk/man/i386_io_port_list.html @@ -1 +1,38 @@ -<h2>i386_io_port_list</h2> <hr> <p> <strong>Function</strong> - List the devices that permit target thread to invoke operations. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t i386_io_port_list</strong> <strong>(thread_act_t</strong> <var>target_act</var>, <strong>device_list_t</strong> <var>device_list</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_act</var> <dd> [in thread send right] Thread whose permission list is to be returned. <p> <dt> <var>device_list</var> <dd> [out pointer to dynamic array of device send rights] Device ports permitting I/O. </dl> <h3>DESCRIPTION</h3> <p> The <strong>i386_io_port_list</strong> function returns a list of the devices named in the thread's I/O permission bitmap, namely those permitting I/O instructions to be executed against them. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="i386_io_port_add.html"><strong>i386_io_port_add<strong></a>, <a href="i386_io_port_remove.html"><strong>i386_io_port_remove<strong></a>. \ No newline at end of file +<h2>i386_io_port_list</h2> +<hr> +<p> +<strong>Function</strong> - List the devices that permit target thread to invoke operations. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t i386_io_port_list</strong> + <strong>(thread_act_t</strong> <var>target_act</var>, + <strong>device_list_t</strong> <var>device_list</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_act</var> +<dd> +[in thread send right] +Thread whose permission list is to be returned. +<p> +<dt> <var>device_list</var> +<dd> +[out pointer to dynamic array of device send rights] +Device ports +permitting I/O. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>i386_io_port_list</strong> function returns a list of the +devices named in the +thread's I/O permission bitmap, namely those permitting I/O instructions to be +executed against them. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="i386_io_port_add.html"><strong>i386_io_port_add<strong></a>, +<a href="i386_io_port_remove.html"><strong>i386_io_port_remove<strong></a>. diff --git a/osfmk/man/i386_io_port_remove.html b/osfmk/man/i386_io_port_remove.html index 31ead08a0..dfd9f14b3 100755 --- a/osfmk/man/i386_io_port_remove.html +++ b/osfmk/man/i386_io_port_remove.html @@ -1 +1,38 @@ -<h2>i386_io_port_remove</h2> <hr> <p> <strong>Function</strong> - Disable target thread's ability to invoke operations on the specified device. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t i386_io_port_remove</strong> <strong>(thread_act_t</strong> <var>target_act</var>, <strong>device_t</strong> <var>device</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_act</var> <dd> [in thread send right] Thread whose permission bitmap is to be cleared <p> <dt> <var>device</var> <dd> [in device send right] Device whose permission is to be revoked </dl> <h3>DESCRIPTION</h3> <p> The <strong>i386_io_port_remove</strong> function removes the specified device from the thread's I/O permission bitmap, thereby prohibiting I/O instructions being executed against the device. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="i386_io_port_add.html"><strong>i386_io_port_add<strong></a>, <a href="i386_io_port_list.html"><strong>i386_io_port_list<strong></a>. \ No newline at end of file +<h2>i386_io_port_remove</h2> +<hr> +<p> +<strong>Function</strong> - Disable target thread's ability to invoke operations on the +specified device. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t i386_io_port_remove</strong> + <strong>(thread_act_t</strong> <var>target_act</var>, + <strong>device_t</strong> <var>device</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_act</var> +<dd> +[in thread send right] +Thread whose permission bitmap is to be cleared +<p> +<dt> <var>device</var> +<dd> +[in device send right] +Device whose permission is to be revoked +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>i386_io_port_remove</strong> function removes the specified +device from the +thread's I/O permission bitmap, thereby prohibiting I/O instructions being +executed against the device. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="i386_io_port_add.html"><strong>i386_io_port_add<strong></a>, +<a href="i386_io_port_list.html"><strong>i386_io_port_list<strong></a>. diff --git a/osfmk/man/i386_set_ldt.html b/osfmk/man/i386_set_ldt.html index 4ae173510..31627a9bc 100755 --- a/osfmk/man/i386_set_ldt.html +++ b/osfmk/man/i386_set_ldt.html @@ -1 +1,90 @@ -<h2>i386_set_ldt</h2> <hr> <p> <strong>Function</strong> - Set per-thread segment descriptors. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t i386_set_ldt</strong> <strong>(thread_act_t</strong> <var>target_act</var>, <strong>int</strong> <var>first_selector</var>, <strong>descriptor_list_t</strong> <var>desc_list</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_act</var> <dd> [in thread send right] Thread whose segment descriptors are to be set. <p> <dt> <var>first_selector</var> <dd> [in scalar] Selector value (segment register value) corresponding to the first segment whose descriptor is to be set. <p> <dt> <var>desc_list</var> <dd> [pointer to in array of <strong>descriptor_t</strong>] Array of segment descriptors. The following forms are permitted: <ul> <p> <li> Empty descriptor. The <strong>ACC_P</strong> flag (segment present) may or may not be set. <p> <li> <strong>ACC_CALL_GATE</strong>--Converted into a system call gate. The <strong>ACC_P</strong> flag must be set. </ul> <p> All other descriptors must have both the <strong>ACC_P</strong> flag set and specify user mode access (<strong>ACC_PL_U</strong>). <ul> <p> <li> <strong>ACC_DATA</strong>. <p> <li> <strong>ACC_DATA_W</strong>. <p> <li> <strong>ACC_DATA_E</strong>. <p> <li> <strong>ACC_DATA_EW</strong>. <p> <li> <strong>ACC_CODE</strong>. <p> <li> <strong>ACC_CODE_R</strong>. <p> <li> <strong>ACC_CODE_C</strong>. <p> <li> <strong>ACC_CODE_CR</strong>. <p> <li> <strong>ACC_CALL_GATE_16</strong>. <p> <li> <strong>ACC_CALL_GATE</strong>. </ul> </dl> <h3>DESCRIPTION</h3> <p> The <strong>i386_set_ldt</strong> function allows a thread to have a private local descriptor table (LDT) which allows its local segments to map various ranges of its address space. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="i386_get_ldt.html"><strong>i386_get_ldt<strong></a>. \ No newline at end of file +<h2>i386_set_ldt</h2> +<hr> +<p> +<strong>Function</strong> - Set per-thread segment descriptors. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t i386_set_ldt</strong> + <strong>(thread_act_t</strong> <var>target_act</var>, + <strong>int</strong> <var>first_selector</var>, + <strong>descriptor_list_t</strong> <var>desc_list</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_act</var> +<dd> +[in thread send right] +Thread whose segment descriptors are to be set. +<p> +<dt> <var>first_selector</var> +<dd> +[in scalar] +Selector value (segment register value) corresponding to the +first segment whose descriptor is to be set. +<p> +<dt> <var>desc_list</var> +<dd> +[pointer to in array of <strong>descriptor_t</strong>] +Array of segment descriptors. The +following forms are permitted: +<ul> +<p> +<li> +Empty descriptor. The <strong>ACC_P</strong> flag (segment present) may or may +not be set. +<p> +<li> +<strong>ACC_CALL_GATE</strong>--Converted into a system call gate. The +<strong>ACC_P</strong> flag must be set. +</ul> +<p> +All other descriptors must have both the <strong>ACC_P</strong> flag set and specify +user mode access (<strong>ACC_PL_U</strong>). +<ul> +<p> +<li> +<strong>ACC_DATA</strong>. +<p> +<li> +<strong>ACC_DATA_W</strong>. +<p> +<li> +<strong>ACC_DATA_E</strong>. +<p> +<li> +<strong>ACC_DATA_EW</strong>. +<p> +<li> +<strong>ACC_CODE</strong>. +<p> +<li> +<strong>ACC_CODE_R</strong>. +<p> +<li> +<strong>ACC_CODE_C</strong>. +<p> +<li> +<strong>ACC_CODE_CR</strong>. +<p> +<li> +<strong>ACC_CALL_GATE_16</strong>. +<p> +<li> +<strong>ACC_CALL_GATE</strong>. +</ul> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>i386_set_ldt</strong> function allows a thread to have a +private local descriptor +table (LDT) which allows its local segments to map various ranges +of its address +space. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="i386_get_ldt.html"><strong>i386_get_ldt<strong></a>. diff --git a/osfmk/man/index.html b/osfmk/man/index.html index 1df1cd2cd..551c2e30d 100755 --- a/osfmk/man/index.html +++ b/osfmk/man/index.html @@ -1 +1,455 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>Mach Kernel Interface Reference Manual</title> </head> <body> <h3>Mach IPC Interface</h3> <blockquote> <p> 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.</p> <h4>Mach Message Queue Interface</h4> <blockquote> <p> <a href="mach_msg.html">mach_msg</a> - Send and/or receive a message from the target port.<br> <a href="mach_msg.html">mach_msg_overwrite</a> - Send and/or receive messages with possible overwrite.<br> </p> Mach Message Queue Data Structures <p> <a href="mach_msg_descriptor.html">mach_msg_descriptor</a> - Specifies an element of a complex IPC message.<br> <a href="mach_msg_header.html">mach_msg_header</a> - Specifies the content of an IPC message header.<br> </p> </blockquote> <h4>Mach Lock-Set Interface</h4> <blockquote> <p> <a href="lock_acquire.html">lock_acquire</a> - Acquire ownership a lock<br> <a href="lock_handoff.html">lock_handoff</a> - Hand-off ownership of a lock.<br> <a href="lock_handoff_accept.html">lock_handoff_accept</a> - Accept lock ownership from a handoff.<br> <a href="lock_make_stable.html">lock_make_stable</a> - Stabilize the state of the specified lock.<br> <a href="lock_release.html">lock_release</a> - Release ownership of a lock.<br> <a href="lock_set_create.html">lock_set_create</a> - Create a new lock set.<br> <a href="lock_set_destroy.html">lock_set_destroy</a> - Destroy a lock set and its associated locks.<br> <a href="lock_try.html">lock_try</a> - Attempt to acquire access rights to a lock.<br> </p> </blockquote> <h4>Mach Semaphore Interface</h4> <blockquote> <p> <a href="semaphore_create.html">semaphore_create</a> - Create a new semaphore.<br> <a href="semaphore_destroy.html">semaphore_destroy</a> - Destroy a semaphore.<br> <a href="semaphore_signal.html">semaphore_signal</a> - Increments the semaphore count.<br> <a href="semaphore_signal_all.html">semaphore_signal_all</a> - Wake up all threads blocked on a semaphore.<br> <a href="semaphore_wait.html">semaphore_wait</a> - Wait on the specified semaphore.<br> </p> </blockquote> <h4>Mach Port Management Interface</h4> <blockquote> <p> <a href="mach_port_allocate.html">mach_port_allocate</a> - Create caller-specified type of port right.<br> <a href="mach_port_allocate_full.html">mach_port_allocate_full</a> - Create a port right with full Mach port semantics.<br> <a href="mach_port_allocate_name.html">mach_port_allocate_name</a> - Create a port right with the caller-specified name.<br> <a href="mach_port_allocate_qos.html">mach_port_allocate_qos</a> - Allocate a port with specified "quality of service".<br> <a href="MP_allocate_subsystem.html">mach_port_allocate_subsystem</a> - Create a port right associated with the caller-specified subsystem.<br> <a href="mach_port_deallocate.html">mach_port_deallocate</a> - Decrement the target port right's user reference count.<br> <a href="mach_port_destroy.html">mach_port_destroy</a> - Deallocate all port rights associated with specified name.<br> <a href="mach_port_extract_right.html">mach_port_extract_right</a> - Remove the specified right from the target task and return it to the caller.<br> <a href="mach_port_get_attributes.html">mach_port_get_attributes</a> - Return information about target port as specified by the caller.<br> <a href="mach_port_get_refs.html">mach_port_get_refs</a> - Return the current count of user references on the target port right.<br> <a href="mach_port_get_set_status.html">mach_port_get_set_status</a> - Return the port right names contained in the target port set.<br> <a href="mach_port_insert_right.html">mach_port_insert_right</a> - Insert the specified port right into the target task.<br> <a href="mach_port_mod_refs.html">mach_port_mod_refs</a> - Modify the specified port right's count of user references.<br> <a href="mach_port_move_member.html">mach_port_move_member</a> - Move the specified receive right into or out of the specified port set.<br> <a href="mach_port_names.html">mach_port_names</a> - Return information about a task's port name space.<br> <a href="MP_request_notification.html">mach_port_request_notification</a> - Request notification of the specified port event type.<br> <a href="mach_port_set_attributes.html">mach_port_set_attributes</a> - Set the target port's attributes.<br> <a href="mach_port_set_mscount.html">mach_port_set_mscount</a> - Change the target port's make-send count.<br> <a href="mach_port_set_seqno.html">mach_port_set_seqno</a> - Change the current value of the target port's sequence number.<br> <a href="mach_port_type.html">mach_port_type</a> - Return the characteristics of the target port name.<br> <a href="mach_reply_port.html">mach_reply_port</a> - Allocate a new port and insert corresponding receive right in the calling task.<br> <a href="mach_subsystem_create.html"> mach_subsystem_create</a> - Used by a server to register information about an RPC subsystem with the kernel.<br> </p> Mach Port Data Structures <p> <a href="mach_port_limits.html">mach_port_limits</a> - Specifies a port's resource and message queue limits.<br> <a href="mach_port_qos.html">mach_port_qos</a> - Specifies a port's attributes with respect to "Quality Of Service."<br> <a href="mach_port_status.html">mach_port_status</a> - Used to present a port's current status with respect to various important attributes.<br> </p> Mach Port Notification Callbacks <p> <a href="do_mach_notify_dead_name.html">do_mach_notify_dead_name</a> - Handle the current instance of a dead-name notification.<br> <a href="do_mach_notify_no_senders.html">do_mach_notify_no_senders</a> - Handle the current instance of a no-more-senders notification.<br> <a href="DMN_port_deleted.html">do_mach_notify_port_deleted</a> - Handle the current instance of a port-deleted notification.<br> <a href="DMN_port_destroyed.html">do_mach_notify_port_destroyed</a> - Handle the current instance of a port-destroyed notification.<br> <a href="do_mach_notify_send_once.html">do_mach_notify_send_once</a> - Handle the current instance of a send-once notification.<br> </p> Mach Port Notification Callback Server Helpers <p> <a href="notify_server.html">notify_server</a> - Detect and handle a kernel-generated IPC notification.<br> </p> </blockquote> </blockquote> <h3>Mach Virtual Memory Interface</h3> <blockquote> <h4>Mach Virtual Memory Address Space Manipulation Interface</h4> <blockquote> <p> <a href="host_page_size.html">host_page_size</a> - Provide the system's virtual page size.<br> <a href="vm_allocate.html">vm_allocate</a> - Allocate a region of virtual memory.<br> <a href="vm_behavior_set.html">vm_behavior_set</a> - Specify expected access patterns for the target VM region.<br> <a href="vm_copy.html">vm_copy</a> - Copy a region of virtual memory.<br> <a href="vm_deallocate.html">vm_deallocate</a> - Deallocate a region of virtual memory.<br> <a href="vm_inherit.html">vm_inherit</a> - Set a VM region's inheritance attribute.<br> <a href="vm_machine_attribute.html">vm_machine_attribute</a> - Get/set the target memory region's special attributes.<br> <a href="vm_map.html">vm_map</a> - Map the specified memory object to a region of virtual memory.<br> <a href="vm_msync.html">vm_msync</a> - Synchronize the specified region of virtual memory.<br> <a href="vm_protect.html">vm_protect</a> - Set access privilege attribute for a region of virtual memory.<br> <a href="vm_read.html">vm_read</a> - Read the specified range of target task's address space.<br> <a href="vm_region.html">vm_region</a> - Return description of a virtual memory region.<br> <a href="vm_remap.html">vm_remap</a> - Map memory objects in one address space to that of another's.<br> <a href="vm_wire.html"> vm_wire</a> - Modify the target region's paging characteristics.<br> <a href="vm_write.html">vm_write</a> - Write data to the specified address in the target address space.<br> </p> Data Structures <p> <a href="vm_region_basic_info.html">vm_region_basic_info</a> - Defines the attributes of a task's memory region.<br> <a href="vm_statistics.html">vm_statistics</a> - Defines statistics for the kernel's use of virtual memory.<br> </p> </blockquote> <h4>External Memory Management Interface</h4> <blockquote> 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.<br> <p> <a href="MO_change_attributes.html">memory_object_change_attributes</a> - Modify subset of memory object attributes.<br> <a href="memory_object_destroy.html">memory_object_destroy</a> - Shut down a memory object.<br> <a href="MO_get_attributes.html">memory_object_get_attributes</a> - Return current attributes for a memory object.<br> <a href="memory_object_lock_request.html">memory_object_lock_request</a> - Restrict access to memory object data.<br> <a href="MO_SY_completed.html">memory_object_synchronize_completed</a> - Synchronized data has been processed.<br> </p> Data Structures <p> <a href="memory_object_attr_info.html">memory_object_attr_info</a> - Defines memory object attributes.<br> <a href="memory_object_perf_info.html">memory_object_perf_info</a>- Specifies performance-related memory object attributes.<br> </p> External Memory Manager Interface Callbacks <p> <a href="memory_object_create.html">memory_object_create</a> - Assign a new memory object to the default memory manager.<br> <a href="MO_data_initialize.html">memory_object_data_initialize</a> - Provide initial data for a new memory object.<br> <a href="memory_object_data_request.html">memory_object_data_request</a> - Request that memory manager page-in specified data.<br> <a href="memory_object_data_return.html">memory_object_data_return</a> - Return memory object data to the appropriate memory manager.<br> <a href="memory_object_data_unlock.html">memory_object_data_unlock</a> - Request a memory manager release the lock on specific data.<br> <a href="memory_object_init.html">memory_object_init</a> - Inform a memory manager on first use of a memory object.<br> <a href="memory_object_synchronize.html">memory_object_synchronize</a> - Request synchronization of data with backing store.<br> <a href="memory_object_terminate.html">memory_object_terminate</a> - Relinquish access to a memory object.<br> </p> EMMI Callback Server Helpers <p> <a href="MO_default_server.html">memory_object_default_server</a> - Handle kernel operation request targeted for the default pager.<br> <a href="memory_object_server.html">memory_object_server</a> - Handle kernel operation request aimed at a given memory manager.<br> </p> </blockquote> <h4>Default Memory Management Interface</h4> <blockquote> <p> <a href="default_pager_add_segment.html">default_pager_add_segment</a> - Add additional backing storage for a default pager.<br> <a href="DP_backing_store_create.html">default_pager_backing_store_create</a> - Create a backing storage object.<br> <a href="DP_backing_store_delete.html"> default_pager_backing_store_delete</a> - Delete a backing storage object.<br> <a href="DP_backing_store_info.html">default_pager_backing_store_info</a> - Return information about a backing storage object.<br> <a href="default_pager_info.html">default_pager_info</a> - Furnish caller with information about the default pager.<br> <a href="DP_object_create.html">default_pager_object_create</a> - Initialize a non-persistent memory object.<br> <a href="HD_memory_manager.html">host_default_memory_manager</a> - Register/Lookup the host's default pager.<br> </p> </blockquote> </blockquote> <h3>Process Management Interface</h3> <blockquote> <h4>Task Interface</h4> <blockquote> <p> <a href="mach_ports_lookup.html">mach_ports_lookup</a> - Provide caller with an array of the target task's well-known ports.<br> <a href="mach_ports_register.html">mach_ports_register</a> - Register an array of well-known ports on behalf of the target task.<br> <a href="mach_task_self.html">mach_task_self</a> - Return a send right to the caller's task_self port.<br> <a href="task_create.html">task_create</a> - Create a new task.<br> <a href="task_get_emulation_vector.html">task_get_emulation_vector</a> - Return an array identifying the target task's user-level system call handlers.<br> <a href="task_get_exception_ports.html">task_get_exception_ports</a> - Return send rights to the target task's exception ports.<br> <a href="task_get_special_port.html">task_get_special_port</a> - Return a send write to the indicated special port.<br> <a href="task_info.html">task_info</a> - Return per-task information according to specified flavor.<br> <a href="task_resume.html">task_resume</a> - Decrement the target task's suspend count.<br> <a href="task_sample.html">task_sample</a> - Sample the target task's thread program counters periodically.<br> <a href="task_set_emulation.html">task_set_emulation</a> - Establish a user-level handler for a system call.<br> <a href="task_set_emulation_vector.html">task_set_emulation_vector</a> - Establish the target task's user-level system call handlers.<br> <a href="task_set_exception_ports.html">task_set_exception_ports</a> - Set target task's exception ports.<br> <a href="task_set_info.html">task_set_info</a> - Set task-specific information state.<br> <a href="task_set_port_space.html">task_set_port_space</a> - Set the size of the target task's port name space table.<br> <a href="task_set_special_port.html">task_set_special_port</a> - Set the indicated special port.<br> <a href="task_suspend.html">task_suspend</a> - Suspend the target task.<br> <a href="task_swap_exception_ports.html">task_swap_exception_ports</a> - Set target task's exception ports, returning the previous exception ports.<br> <a href="task_terminate.html">task_terminate</a> - Terminate the target task and deallocate its resources.<br> <a href="task_threads.html">task_threads</a> - Return the target task's list of threads.<br> </p> Task Data Structures <p> <a href="task_basic_info.html">task_basic_info</a> - Defines basic information for a task.<br> <a href="task_thread_times_info.html">task_thread_times_info</a> - Defines thread execution times information for tasks.<br> </p> </blockquote> <h4>Thread Interface</h4> <blockquote> <p> <a href="mach_thread_self.html">mach_thread_self</a> - Returns the thread self port.<br> <a href="thread_abort.html">thread_abort</a> - Abort a thread.<br> <a href="thread_abort_safely.html">thread_abort_safely</a> - Abort a thread, restartably.<br> <a href="thread_create.html">thread_create</a> - Create a thread within a task.<br> <a href="thread_create_running.html">thread_create_running</a> - Optimized creation of a running thread.<br> <a href="thread_depress_abort.html">thread_depress_abort</a> - Cancel thread scheduling depression.<br> <a href="thread_get_exception_ports.html">thread_get_exception_ports</a> - Return a send right to an exception port.<br> <a href="thread_get_special_port.html">thread_get_special_port</a> - Return a send right to the caller-specified special port.<br> <a href="thread_get_state.html">thread_get_state</a> - Return the execution state for a thread.<br> <a href="thread_info.html">thread_info</a> - Return information about a thread.<br> <a href="thread_resume.html">thread_resume</a> - Resume a thread.<br> <a href="thread_sample.html">thread_sample</a> - Perform periodic PC sampling for a thread.<br> <a href="thread_set_exception_ports.html">thread_set_exception_ports</a> - Set exception ports for a thread.<br> <a href="thread_set_special_port.html">thread_set_special_port</a> - Set caller-specified special port belonging to the target thread.<br> <a href="thread_set_state.html">thread_set_state</a> - Set the target thread's user-mode execution state.<br> <a href="thread_suspend.html">thread_suspend</a> - Suspend a thread.<br> <a href="TS_exception_ports.html">thread_swap_exception_ports</a> - Swap exception ports for a thread.<br> <a href="thread_terminate.html">thread_terminate</a> - Destroy a thread.<br> <a href="thread_wire.html">thread_wire</a> - Mark the thread as privileged with respect to kernel resources.<br> </p> Thread Data Structures <p> <a href="thread_basic_info.html">thread_basic_info</a> - Defines basic information for a thread.<br> </p> Thread Exception Callbacks <p> <a href="catch_exception_raise.html">catch_exception_raise</a> - Handles the occurrence of an exception within a thread.<br> </p> Thread Exception Callback Server Helpers <p> <a href="exc_server.html">exc_server</a> - Handle kernel-reported thread exception.<br> </p> </blockquote> <h4>Scheduling Interface</h4> <blockquote> <p> <a href="task_policy.html">task_policy</a> - Set target task's default scheduling policy state.<br> <a href="task_set_policy.html">task_set_policy</a> - Set target task's default scheduling policy state.<br> <a href="thread_policy.html">thread_policy</a> - Set target thread's scheduling policy state.<br> <a href="thread_set_policy.html">thread_set_policy</a> - Set target thread's scheduling policy state.<br> <a href="thread_switch.html">thread_switch</a> - Cause context switch with options.<br> </p> Scheduling Data Structures <p> <a href="policy_fifo_info.html">policy_fifo_info</a> - Specifies information associated with the system's First-In-First-Out scheduling policy.<br> <a href="policy_rr_info.html">policy_rr_info</a> - Specifies information associated with the system's Round Robin scheduling policy.<br> <a href="policy_timeshare_info.html">policy_timeshare_info</a> - Specifies information associated with the system's Timeshare scheduling policy.<br> </p> </blockquote> </blockquote> <h3>System Management Interface</h3> <blockquote> <h4>Host Interface</h4> <blockquote> <p> <a href="host_get_clock_service.html">host_get_clock_service</a> - Return a send right to a kernel clock's service port.<br> <a href="host_get_time.html">host_get_time</a> - Returns the current time as seen by that host.<br> <a href="host_info.html">host_info</a> - Return information about a host.<br> <a href="host_kernel_version.html">host_kernel_version</a> - Return kernel version information for a host.<br> <a href="host_statistics.html">host_statistics</a> - Return statistics for a host.<br> <a href="mach_host_self.html">mach_host_self</a> - Returns send rights to the task's host self port.<br> </p> Data Structures <p> <a href="host_basic_info.html">host_basic_info</a> - Used to present basic information about a host.<br> <a href="host_load_info.html">host_load_info</a> - Used to present a host's processor load information.<br> <a href="host_sched_info.html">host_sched_info</a> - - Used to present the set of scheduler limits associated with the host.<br> <a href="kernel_resource_sizes.html">kernel_resource_sizes</a> - Used to present the sizes of kernel's major structures.<br> </p> </blockquote> <h4>Host Control Interface</h4> <blockquote> <p> <a href="host_adjust_time.html">host_adjust_time</a> - Arranges for the time on a specified host to be gradually changed by an adjustment value.<br> <a href="HD_memory_manager.html">host_default_memory_manager</a> - Set the default memory manager.<br> <a href="host_get_boot_info.html">host_get_boot_info</a> - Return operator boot information.<br> <a href="host_get_clock_control.html">host_get_clock_control</a> - Return a send right to a kernel clock's control port.<br> <a href="host_processor_slots.html">host_processor_slots</a> - Return a list of numbers that map processor slots to active processors.<br> <a href="host_processors.html">host_processors</a> - Return a list of send rights representing all processor ports.<br> <a href="host_reboot.html">host_reboot</a> - Reboot this host.<br> <a href="host_set_time.html">host_set_time</a> - Establishes the time on the specified host.<br> </p> </blockquote> <h4>Host Security Interface</h4> <blockquote> <p> <a href="host_security_create_task_token.html">host_security_create_task_token</a> - Create a new task with an explicit security token.<br> <a href="host_security_set_task_token.html">host_security_set_task_token</a> - Change the target task's security token.<br> </p> </blockquote> <h4>Resource Accounting Interface</h4> <blockquote> <i> The Mach resource accounting mechanism is not functional in the current Mac OS X/Darwin system. It will become functional in a future release. </i> <p> <a href="ledger_create.html">ledger_create</a> - Create a subordinate ledger.<br> <a href="ledger_read.html">ledger_read</a> - Return the ledger limit and balance.<br> <a href="ledger_terminate.html">ledger_terminate</a> - Destroy a ledger.<br> <a href="ledger_transfer.html">ledger_transfer</a> - Transfer resources from a parent ledger to a child.<br> </p> </blockquote> <h4>Processor Management Interface</h4> <blockquote> <p> <a href="processor_control.html">processor_control</a> - Perform caller-specified operation on target processor.<br> <a href="processor_exit.html">processor_exit</a> - Exit a processor.<br> <a href="processor_info.html">processor_info</a> - Return information about a processor.<br> <a href="processor_start.html">processor_start</a> - Start a processor.<br> </p> Processor Data Structures <p> <a href="processor_basic_info.html">processor_basic_info</a> - Defines the basic information about a processor.<br> </p> </blockquote> <h4>Processor Set Interface</h4> <blockquote> <i> The processor set interface allows for the grouping of tasks and processors for the purpose of exclusive scheduling. These interface are <b>deprecated</b> 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. </i> <p> <a href="host_processor_sets.html">host_processor_sets</a> - Return a list of send rights representing all processor set name ports.<br> <a href="host_processor_set_priv.html">host_processor_set_priv</a> - Translate a processor set name port into a processor set control port.<br> <a href="processor_assign.html">processor_assign</a> - Assign a processor to a processor set.<br> <a href="processor_get_assignment.html">processor_get_assignment</a> - Get current assignment for a processor.<br> <a href="processor_set_create.html">processor_set_create</a> - Create a new processor set.<br> <a href="processor_set_default.html">processor_set_default</a> - Return the default processor set.<br> <a href="processor_set_destroy.html">processor_set_destroy</a> - Destroy the target processor set.<br> <a href="processor_set_info.html">processor_set_info</a> - Return processor set state according to caller-specified flavor.<br> <a href="processor_set_max_priority.html">processor_set_max_priority</a> - Sets the maximum scheduling priority for a processor set.<br> <a href="P_set_policy_control.html">processor_set_policy_control</a> - Set target processor set's scheduling policy state.<br> <a href="P_set_policy_disable.html">processor_set_policy_disable</a> - Enables a scheduling policy for a processor set.<br> <a href="P_set_policy_enable.html">processor_set_policy_enable</a> - Enables a scheduling policy for a processor set.<br> <a href="processor_set_statistics.html">processor_set_statistics</a> - Return scheduling statistics for a processor set.<br> <a href="processor_set_tasks.html">processor_set_tasks</a> - Return all tasks currently assigned to the target processor set.<br> <a href="processor_set_threads.html">processor_set_threads</a> - Return all threads currently assigned to the target processor set.<br> <a href="task_assign.html">task_assign</a> - Assign a task to a processor set.<br> <a href="task_assign_default.html">task_assign_default</a> - Assign a task to the default processor set.<br> <a href="task_get_assignment.html">task_get_assignment</a> - Create a new task with an explicit security token.<br> <a href="thread_assign.html">thread_assign</a> - Assign a thread to a processor set.<br> <a href="thread_assign_default.html">thread_assign_default</a> - Assign a thread to the default processor set.<br> <a href="thread_get_assignment.html">thread_get_assignment</a> - Return the processor set to which a thread is assigned.<br> </p> Processor Set Data Structures <p> <a href="processor_set_basic_info.html">processor_set_basic_info</a> - Defines the basic information about a processor set.<br> <a href="processor_set_load_info.html">processor_set_load_info</a> - Defines the scheduling statistics for a processor set.<br> </p> </blockquote> <h4>Clock Interface</h4> <blockquote> <p> <a href="clock_alarm.html">clock_alarm</a> - Set up an alarm.<br> <a href="clock_get_attributes.html">clock_get_attributes</a> - Return attributes of a clock.<br> <a href="clock_get_time.html">clock_get_time</a> - Return the current time.<br> <a href="clock_map_time.html">clock_map_time</a> - Return a memory object that maps a clock.<br> <a href="clock_set_attributes.html">clock_set_attributes</a> - Set a particular clock's attributes.<br> <a href="clock_set_time.html">clock_set_time</a> - Set the current time.<br> <a href="clock_sleep.html">clock_sleep</a> - Delay the invoking thread until a specified time.<br> </p> Clock Data Structures <p> <a href="mapped_tvalspec.html">mapped_tvalspec</a> - Specifies the format the kernel uses to maintain a mapped clock's time.<br> <a href="tvalspec.html">tvalspec</a> - Defines format of system time values.<br> </p> Clock Interface Callbacks <p> <a href="clock_alarm_reply.html">clock_alarm_reply</a> - Ring a preset alarm.<br> </p> Clock Callback Server Helpers <p> <a href="clock_reply_server.html"> clock_reply_server</a> - Handle kernel-generated alarm.<br> </p> </blockquote> <h4>Multi-Computer Support Interface</h4> <blockquote> <i> 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. </i> <p> <a href="host_page_size.html">host_page_size</a> - Returns the page size for the given host.<br> <a href="ledger_get_remote.html">ledger_get_remote</a> - Return send right to specified host's remote ledger port.<br> <a href="ledger_set_remote.html">ledger_set_remote</a> - Set this host's remote ledger port.<br> <a href="norma_get_special_port.html">norma_get_special_port</a> - Returns a send right for a specified node-specific special port.<br> <a href="norma_node_self.html">norma_node_self</a> - Return the node index of the current host.<br> <a href="norma_port_location_hint.html">norma_port_location_hint</a> - Guess a port's current location.<br> <a href="norma_set_special_port.html">norma_set_special_port</a> - Set node-specific special port.<br> <a href="norma_task_clone.html">norma_task_clone</a> - Create a remote task that shares access to parent task's memory.<br> <a href="norma_task_create.html">norma_task_create</a> - Create a remote task using task_create semantics.<br> <a href="norma_task_teleport.html">norma_task_teleport</a> - "Clone" a task on a specified node.<br> </p> </blockquote> </blockquote> <h3>Machine Specific Interface</h3> <blockquote> <h4>Intel 386 Support</h4> <blockquote> <p> <a href="i386_get_ldt.html">i386_get_ldt</a> - Returns per-thread segment descriptors from the local descriptor table (LDT).<br> <a href="i386_io_port_add.html">i386_io_port_add</a> - Adds a device to the I/O permission bitmap for a thread. <br> <a href="i386_io_port_list.html">i386_io_port_list</a> - Returns a list of the devices named in the thread's I/O permission bitmap.<br> <a href="i386_io_port_remove.html">i386_io_port_remove</a> - Removes the specified device from the thread's I/O permission bitmap.<br> <a href="i386_set_ldt.html">i386_set_ldt</a> - Allows a thread to have a private local descriptor table (LDT).<br> </p> </blockquote> <h4>PowerPC Support</h4> <blockquote> <p> </p> </blockquote> </blockquote> </BODY> </HTML> \ No newline at end of file +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>Mach Kernel Interface Reference Manual</title> +</head> +<body> +<h3>Mach IPC Interface</h3> +<blockquote> +<p> +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.</p> + +<h4>Mach Message Queue Interface</h4> +<blockquote> +<p> +<a href="mach_msg.html">mach_msg</a> - Send and/or receive a message from the target port.<br> +<a href="mach_msg.html">mach_msg_overwrite</a> - Send and/or receive messages with possible overwrite.<br> +</p> +Mach Message Queue Data Structures +<p> +<a href="mach_msg_descriptor.html">mach_msg_descriptor</a> - Specifies an element of a complex IPC message.<br> +<a href="mach_msg_header.html">mach_msg_header</a> - Specifies the content of an IPC message header.<br> +</p> +</blockquote> + +<h4>Mach Lock-Set Interface</h4> +<blockquote> +<p> +<a href="lock_acquire.html">lock_acquire</a> - Acquire ownership a lock<br> +<a href="lock_handoff.html">lock_handoff</a> - Hand-off ownership of a lock.<br> +<a href="lock_handoff_accept.html">lock_handoff_accept</a> - Accept lock ownership from a handoff.<br> +<a href="lock_make_stable.html">lock_make_stable</a> - Stabilize the state of the specified lock.<br> +<a href="lock_release.html">lock_release</a> - Release ownership of a lock.<br> +<a href="lock_set_create.html">lock_set_create</a> - Create a new lock set.<br> +<a href="lock_set_destroy.html">lock_set_destroy</a> - Destroy a lock set and its associated locks.<br> +<a href="lock_try.html">lock_try</a> - Attempt to acquire access rights to a lock.<br> +</p> +</blockquote> + +<h4>Mach Semaphore Interface</h4> +<blockquote> +<p> +<a href="semaphore_create.html">semaphore_create</a> - Create a new semaphore.<br> +<a href="semaphore_destroy.html">semaphore_destroy</a> - Destroy a semaphore.<br> +<a href="semaphore_signal.html">semaphore_signal</a> - Increments the semaphore count.<br> +<a href="semaphore_signal_all.html">semaphore_signal_all</a> - Wake up all threads blocked on a semaphore.<br> +<a href="semaphore_wait.html">semaphore_wait</a> - Wait on the specified semaphore.<br> +</p> +</blockquote> + +<h4>Mach Port Management Interface</h4> +<blockquote> +<p> +<a href="mach_port_allocate.html">mach_port_allocate</a> - Create caller-specified type of port right.<br> +<a href="mach_port_allocate_full.html">mach_port_allocate_full</a> - Create a port right with full Mach port semantics.<br> +<a href="mach_port_allocate_name.html">mach_port_allocate_name</a> - Create a port right with the caller-specified name.<br> +<a href="mach_port_allocate_qos.html">mach_port_allocate_qos</a> - Allocate a port with specified "quality of service".<br> +<a href="MP_allocate_subsystem.html">mach_port_allocate_subsystem</a> - Create a port right associated with the caller-specified subsystem.<br> +<a href="mach_port_deallocate.html">mach_port_deallocate</a> - Decrement the target port right's user reference count.<br> +<a href="mach_port_destroy.html">mach_port_destroy</a> - Deallocate all port rights associated with specified name.<br> +<a href="mach_port_extract_right.html">mach_port_extract_right</a> - Remove the specified right from the target task and return it to the caller.<br> +<a href="mach_port_get_attributes.html">mach_port_get_attributes</a> - Return information about target port as specified by the caller.<br> +<a href="mach_port_get_refs.html">mach_port_get_refs</a> - Return the current count of user references on the target port right.<br> +<a href="mach_port_get_set_status.html">mach_port_get_set_status</a> - Return the port right names contained in the target port set.<br> +<a href="mach_port_insert_right.html">mach_port_insert_right</a> - Insert the specified port right into the target task.<br> +<a href="mach_port_mod_refs.html">mach_port_mod_refs</a> - Modify the specified port right's count of user references.<br> +<a href="mach_port_move_member.html">mach_port_move_member</a> - Move the specified receive right into or out of the specified port set.<br> +<a href="mach_port_names.html">mach_port_names</a> - Return information about a task's port name space.<br> +<a href="MP_request_notification.html">mach_port_request_notification</a> - Request notification of the specified port event type.<br> +<a href="mach_port_set_attributes.html">mach_port_set_attributes</a> - Set the target port's attributes.<br> +<a href="mach_port_set_mscount.html">mach_port_set_mscount</a> - Change the target port's make-send count.<br> +<a href="mach_port_set_seqno.html">mach_port_set_seqno</a> - Change the current value of the target port's sequence number.<br> +<a href="mach_port_type.html">mach_port_type</a> - Return the characteristics of the target port name.<br> +<a href="mach_reply_port.html">mach_reply_port</a> - Allocate a new port and insert corresponding receive right in the calling task.<br> +<a href="mach_subsystem_create.html"> mach_subsystem_create</a> - Used by a server to register information about an RPC subsystem with the kernel.<br> +</p> +Mach Port Data Structures +<p> +<a href="mach_port_limits.html">mach_port_limits</a> - Specifies a port's resource and message queue limits.<br> +<a href="mach_port_qos.html">mach_port_qos</a> - Specifies a port's attributes with respect to "Quality Of Service."<br> +<a href="mach_port_status.html">mach_port_status</a> - Used to present a port's current status with respect to various important attributes.<br> +</p> +Mach Port Notification Callbacks +<p> +<a href="do_mach_notify_dead_name.html">do_mach_notify_dead_name</a> - Handle the current instance of a dead-name notification.<br> +<a href="do_mach_notify_no_senders.html">do_mach_notify_no_senders</a> - Handle the current instance of a no-more-senders notification.<br> +<a href="DMN_port_deleted.html">do_mach_notify_port_deleted</a> - Handle the current instance of a port-deleted notification.<br> +<a href="DMN_port_destroyed.html">do_mach_notify_port_destroyed</a> - Handle the current instance of a port-destroyed notification.<br> +<a href="do_mach_notify_send_once.html">do_mach_notify_send_once</a> - Handle the current instance of a send-once notification.<br> +</p> +Mach Port Notification Callback Server Helpers +<p> +<a href="notify_server.html">notify_server</a> - Detect and handle a kernel-generated IPC notification.<br> +</p> +</blockquote> + +</blockquote> + +<h3>Mach Virtual Memory Interface</h3> +<blockquote> +<h4>Mach Virtual Memory Address Space Manipulation Interface</h4> +<blockquote> +<p> +<a href="host_page_size.html">host_page_size</a> - Provide the system's virtual page size.<br> +<a href="vm_allocate.html">vm_allocate</a> - Allocate a region of virtual memory.<br> +<a href="vm_behavior_set.html">vm_behavior_set</a> - Specify expected access patterns for the target VM region.<br> +<a href="vm_copy.html">vm_copy</a> - Copy a region of virtual memory.<br> +<a href="vm_deallocate.html">vm_deallocate</a> - Deallocate a region of virtual memory.<br> +<a href="vm_inherit.html">vm_inherit</a> - Set a VM region's inheritance attribute.<br> +<a href="vm_machine_attribute.html">vm_machine_attribute</a> - Get/set the target memory region's special attributes.<br> +<a href="vm_map.html">vm_map</a> - Map the specified memory object to a region of virtual memory.<br> +<a href="vm_msync.html">vm_msync</a> - Synchronize the specified region of virtual memory.<br> +<a href="vm_protect.html">vm_protect</a> - Set access privilege attribute for a region of virtual memory.<br> +<a href="vm_read.html">vm_read</a> - Read the specified range of target task's address space.<br> +<a href="vm_region.html">vm_region</a> - Return description of a virtual memory region.<br> +<a href="vm_remap.html">vm_remap</a> - Map memory objects in one address space to that of another's.<br> +<a href="vm_wire.html"> vm_wire</a> - Modify the target region's paging characteristics.<br> +<a href="vm_write.html">vm_write</a> - Write data to the specified address in the target address space.<br> +</p> +Data Structures +<p> +<a href="vm_region_basic_info.html">vm_region_basic_info</a> - Defines the attributes of a task's memory region.<br> +<a href="vm_statistics.html">vm_statistics</a> - Defines statistics for the kernel's use of virtual memory.<br> +</p> +</blockquote> + +<h4>External Memory Management Interface</h4> +<blockquote> +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.<br> +<p> +<a href="MO_change_attributes.html">memory_object_change_attributes</a> - Modify subset of memory object attributes.<br> +<a href="memory_object_destroy.html">memory_object_destroy</a> - Shut down a memory object.<br> +<a href="MO_get_attributes.html">memory_object_get_attributes</a> - Return current attributes for a memory object.<br> +<a href="memory_object_lock_request.html">memory_object_lock_request</a> - Restrict access to memory object data.<br> +<a href="MO_SY_completed.html">memory_object_synchronize_completed</a> - Synchronized data has been processed.<br> +</p> +Data Structures +<p> +<a href="memory_object_attr_info.html">memory_object_attr_info</a> - Defines memory object attributes.<br> +<a href="memory_object_perf_info.html">memory_object_perf_info</a>- Specifies performance-related memory object attributes.<br> +</p> +External Memory Manager Interface Callbacks +<p> +<a href="memory_object_create.html">memory_object_create</a> - Assign a new memory object to the default memory manager.<br> +<a href="MO_data_initialize.html">memory_object_data_initialize</a> - Provide initial data for a new memory object.<br> +<a href="memory_object_data_request.html">memory_object_data_request</a> - Request that memory manager page-in specified data.<br> +<a href="memory_object_data_return.html">memory_object_data_return</a> - Return memory object data to the appropriate memory manager.<br> +<a href="memory_object_data_unlock.html">memory_object_data_unlock</a> - Request a memory manager release the lock on specific data.<br> +<a href="memory_object_init.html">memory_object_init</a> - Inform a memory manager on first use of a memory object.<br> +<a href="memory_object_synchronize.html">memory_object_synchronize</a> - Request synchronization of data with backing store.<br> +<a href="memory_object_terminate.html">memory_object_terminate</a> - Relinquish access to a memory object.<br> +</p> +EMMI Callback Server Helpers +<p> +<a href="MO_default_server.html">memory_object_default_server</a> - Handle kernel operation request targeted for the default pager.<br> +<a href="memory_object_server.html">memory_object_server</a> - Handle kernel operation request aimed at a given memory manager.<br> +</p> +</blockquote> + +<h4>Default Memory Management Interface</h4> +<blockquote> +<p> +<a href="default_pager_add_segment.html">default_pager_add_segment</a> - Add additional backing storage for a default pager.<br> +<a href="DP_backing_store_create.html">default_pager_backing_store_create</a> - Create a backing storage object.<br> +<a href="DP_backing_store_delete.html"> default_pager_backing_store_delete</a> - Delete a backing storage object.<br> +<a href="DP_backing_store_info.html">default_pager_backing_store_info</a> - Return information about a backing storage object.<br> +<a href="default_pager_info.html">default_pager_info</a> - Furnish caller with information about the default pager.<br> +<a href="DP_object_create.html">default_pager_object_create</a> - Initialize a non-persistent memory object.<br> +<a href="HD_memory_manager.html">host_default_memory_manager</a> - Register/Lookup the host's default pager.<br> +</p> +</blockquote> + +</blockquote> + +<h3>Process Management Interface</h3> +<blockquote> + +<h4>Task Interface</h4> +<blockquote> +<p> +<a href="mach_ports_lookup.html">mach_ports_lookup</a> - Provide caller with an array of the target task's well-known ports.<br> +<a href="mach_ports_register.html">mach_ports_register</a> - Register an array of well-known ports on behalf of the target task.<br> +<a href="mach_task_self.html">mach_task_self</a> - Return a send right to the caller's task_self port.<br> +<a href="task_create.html">task_create</a> - Create a new task.<br> +<a href="task_get_emulation_vector.html">task_get_emulation_vector</a> - Return an array identifying the target task's user-level system call handlers.<br> +<a href="task_get_exception_ports.html">task_get_exception_ports</a> - Return send rights to the target task's exception ports.<br> +<a href="task_get_special_port.html">task_get_special_port</a> - Return a send write to the indicated special port.<br> +<a href="task_info.html">task_info</a> - Return per-task information according to specified flavor.<br> +<a href="task_resume.html">task_resume</a> - Decrement the target task's suspend count.<br> +<a href="task_sample.html">task_sample</a> - Sample the target task's thread program counters periodically.<br> +<a href="task_set_emulation.html">task_set_emulation</a> - Establish a user-level handler for a system call.<br> +<a href="task_set_emulation_vector.html">task_set_emulation_vector</a> - Establish the target task's user-level system call handlers.<br> +<a href="task_set_exception_ports.html">task_set_exception_ports</a> - Set target task's exception ports.<br> +<a href="task_set_info.html">task_set_info</a> - Set task-specific information state.<br> +<a href="task_set_port_space.html">task_set_port_space</a> - Set the size of the target task's port name space table.<br> +<a href="task_set_special_port.html">task_set_special_port</a> - Set the indicated special port.<br> +<a href="task_suspend.html">task_suspend</a> - Suspend the target task.<br> +<a href="task_swap_exception_ports.html">task_swap_exception_ports</a> - Set target task's exception ports, returning the previous exception ports.<br> +<a href="task_terminate.html">task_terminate</a> - Terminate the target task and deallocate its resources.<br> +<a href="task_threads.html">task_threads</a> - Return the target task's list of threads.<br> +</p> +Task Data Structures +<p> +<a href="task_basic_info.html">task_basic_info</a> - Defines basic information for a task.<br> +<a href="task_thread_times_info.html">task_thread_times_info</a> - Defines thread execution times information for tasks.<br> +</p> +</blockquote> + +<h4>Thread Interface</h4> +<blockquote> +<p> +<a href="mach_thread_self.html">mach_thread_self</a> - Returns the thread self port.<br> +<a href="thread_abort.html">thread_abort</a> - Abort a thread.<br> +<a href="thread_abort_safely.html">thread_abort_safely</a> - Abort a thread, restartably.<br> +<a href="thread_create.html">thread_create</a> - Create a thread within a task.<br> +<a href="thread_create_running.html">thread_create_running</a> - Optimized creation of a running thread.<br> +<a href="thread_depress_abort.html">thread_depress_abort</a> - Cancel thread scheduling depression.<br> +<a href="thread_get_exception_ports.html">thread_get_exception_ports</a> - Return a send right to an exception port.<br> +<a href="thread_get_special_port.html">thread_get_special_port</a> - Return a send right to the caller-specified special port.<br> +<a href="thread_get_state.html">thread_get_state</a> - Return the execution state for a thread.<br> +<a href="thread_info.html">thread_info</a> - Return information about a thread.<br> +<a href="thread_resume.html">thread_resume</a> - Resume a thread.<br> +<a href="thread_sample.html">thread_sample</a> - Perform periodic PC sampling for a thread.<br> +<a href="thread_set_exception_ports.html">thread_set_exception_ports</a> - Set exception ports for a thread.<br> +<a href="thread_set_special_port.html">thread_set_special_port</a> - Set caller-specified special port belonging to the target thread.<br> +<a href="thread_set_state.html">thread_set_state</a> - Set the target thread's user-mode execution state.<br> +<a href="thread_suspend.html">thread_suspend</a> - Suspend a thread.<br> +<a href="TS_exception_ports.html">thread_swap_exception_ports</a> - Swap exception ports for a thread.<br> +<a href="thread_terminate.html">thread_terminate</a> - Destroy a thread.<br> +<a href="thread_wire.html">thread_wire</a> - Mark the thread as privileged with respect to kernel resources.<br> +</p> +Thread Data Structures +<p> +<a href="thread_basic_info.html">thread_basic_info</a> - Defines basic information for a thread.<br> +</p> +Thread Exception Callbacks +<p> +<a href="catch_exception_raise.html">catch_exception_raise</a> - Handles the occurrence of an exception within a thread.<br> +</p> +Thread Exception Callback Server Helpers +<p> +<a href="exc_server.html">exc_server</a> - Handle kernel-reported thread exception.<br> +</p> +</blockquote> + +<h4>Scheduling Interface</h4> +<blockquote> +<p> +<a href="task_policy.html">task_policy</a> - Set target task's default scheduling policy state.<br> +<a href="task_set_policy.html">task_set_policy</a> - Set target task's default scheduling policy state.<br> +<a href="thread_policy.html">thread_policy</a> - Set target thread's scheduling policy state.<br> +<a href="thread_set_policy.html">thread_set_policy</a> - Set target thread's scheduling policy state.<br> +<a href="thread_switch.html">thread_switch</a> - Cause context switch with options.<br> +</p> +Scheduling Data Structures +<p> +<a href="policy_fifo_info.html">policy_fifo_info</a> - Specifies information associated with the system's First-In-First-Out scheduling policy.<br> +<a href="policy_rr_info.html">policy_rr_info</a> - Specifies information associated with the system's Round Robin scheduling policy.<br> +<a href="policy_timeshare_info.html">policy_timeshare_info</a> - Specifies information associated with the system's Timeshare scheduling policy.<br> +</p> +</blockquote> +</blockquote> + +<h3>System Management Interface</h3> +<blockquote> + +<h4>Host Interface</h4> +<blockquote> +<p> +<a href="host_get_clock_service.html">host_get_clock_service</a> - Return a send right to a kernel clock's service port.<br> +<a href="host_get_time.html">host_get_time</a> - Returns the current time as seen by that host.<br> +<a href="host_info.html">host_info</a> - Return information about a host.<br> +<a href="host_kernel_version.html">host_kernel_version</a> - Return kernel version information for a host.<br> +<a href="host_statistics.html">host_statistics</a> - Return statistics for a host.<br> +<a href="mach_host_self.html">mach_host_self</a> - Returns send rights to the task's host self port.<br> +</p> +Data Structures +<p> +<a href="host_basic_info.html">host_basic_info</a> - Used to present basic information about a host.<br> +<a href="host_load_info.html">host_load_info</a> - Used to present a host's processor load information.<br> +<a href="host_sched_info.html">host_sched_info</a> - - Used to present the set of scheduler limits associated with the host.<br> +<a href="kernel_resource_sizes.html">kernel_resource_sizes</a> - Used to present the sizes of kernel's major structures.<br> +</p> +</blockquote> + +<h4>Host Control Interface</h4> +<blockquote> +<p> +<a href="host_adjust_time.html">host_adjust_time</a> - Arranges for the time on a specified host to be gradually changed by an adjustment value.<br> +<a href="HD_memory_manager.html">host_default_memory_manager</a> - Set the default memory manager.<br> +<a href="host_get_boot_info.html">host_get_boot_info</a> - Return operator boot information.<br> +<a href="host_get_clock_control.html">host_get_clock_control</a> - Return a send right to a kernel clock's control port.<br> +<a href="host_processor_slots.html">host_processor_slots</a> - Return a list of numbers that map processor slots to active processors.<br> +<a href="host_processors.html">host_processors</a> - Return a list of send rights representing all processor ports.<br> +<a href="host_reboot.html">host_reboot</a> - Reboot this host.<br> +<a href="host_set_time.html">host_set_time</a> - Establishes the time on the specified host.<br> +</p> +</blockquote> + +<h4>Host Security Interface</h4> +<blockquote> +<p> +<a href="host_security_create_task_token.html">host_security_create_task_token</a> - Create a new task with an explicit security token.<br> +<a href="host_security_set_task_token.html">host_security_set_task_token</a> - Change the target task's security token.<br> +</p> +</blockquote> + +<h4>Resource Accounting Interface</h4> +<blockquote> +<i> +The Mach resource accounting mechanism is not functional in the current Mac OS X/Darwin system. It will become functional in a future release. +</i> +<p> +<a href="ledger_create.html">ledger_create</a> - Create a subordinate ledger.<br> +<a href="ledger_read.html">ledger_read</a> - Return the ledger limit and balance.<br> +<a href="ledger_terminate.html">ledger_terminate</a> - Destroy a ledger.<br> +<a href="ledger_transfer.html">ledger_transfer</a> - Transfer resources from a parent ledger to a child.<br> +</p> +</blockquote> + +<h4>Processor Management Interface</h4> +<blockquote> +<p> +<a href="processor_control.html">processor_control</a> - Perform caller-specified operation on target processor.<br> +<a href="processor_exit.html">processor_exit</a> - Exit a processor.<br> +<a href="processor_info.html">processor_info</a> - Return information about a processor.<br> +<a href="processor_start.html">processor_start</a> - Start a processor.<br> +</p> +Processor Data Structures +<p> +<a href="processor_basic_info.html">processor_basic_info</a> - Defines the basic information about a processor.<br> +</p> +</blockquote> + +<h4>Processor Set Interface</h4> +<blockquote> +<i> +The processor set interface allows for the grouping of tasks and +processors for the purpose of exclusive scheduling. These interface +are <b>deprecated</b> 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. +</i> +<p> +<a href="host_processor_sets.html">host_processor_sets</a> - Return a list of send rights representing all processor set name ports.<br> +<a href="host_processor_set_priv.html">host_processor_set_priv</a> - Translate a processor set name port into a processor set control port.<br> +<a href="processor_assign.html">processor_assign</a> - Assign a processor to a processor set.<br> +<a href="processor_get_assignment.html">processor_get_assignment</a> - Get current assignment for a processor.<br> +<a href="processor_set_create.html">processor_set_create</a> - Create a new processor set.<br> +<a href="processor_set_default.html">processor_set_default</a> - Return the default processor set.<br> +<a href="processor_set_destroy.html">processor_set_destroy</a> - Destroy the target processor set.<br> +<a href="processor_set_info.html">processor_set_info</a> - Return processor set state according to caller-specified flavor.<br> +<a href="processor_set_max_priority.html">processor_set_max_priority</a> - Sets the maximum scheduling priority for a processor set.<br> +<a href="P_set_policy_control.html">processor_set_policy_control</a> - Set target processor set's scheduling policy state.<br> +<a href="P_set_policy_disable.html">processor_set_policy_disable</a> - Enables a scheduling policy for a processor set.<br> +<a href="P_set_policy_enable.html">processor_set_policy_enable</a> - Enables a scheduling policy for a processor set.<br> +<a href="processor_set_statistics.html">processor_set_statistics</a> - Return scheduling statistics for a processor set.<br> +<a href="processor_set_tasks.html">processor_set_tasks</a> - Return all tasks currently assigned to the target processor set.<br> +<a href="processor_set_threads.html">processor_set_threads</a> - Return all threads currently assigned to the target processor set.<br> +<a href="task_assign.html">task_assign</a> - Assign a task to a processor set.<br> +<a href="task_assign_default.html">task_assign_default</a> - Assign a task to the default processor set.<br> +<a href="task_get_assignment.html">task_get_assignment</a> - Create a new task with an explicit security token.<br> +<a href="thread_assign.html">thread_assign</a> - Assign a thread to a processor set.<br> +<a href="thread_assign_default.html">thread_assign_default</a> - Assign a thread to the default processor set.<br> +<a href="thread_get_assignment.html">thread_get_assignment</a> - Return the processor set to which a thread is assigned.<br> +</p> +Processor Set Data Structures +<p> +<a href="processor_set_basic_info.html">processor_set_basic_info</a> - Defines the basic information about a processor set.<br> +<a href="processor_set_load_info.html">processor_set_load_info</a> - Defines the scheduling statistics for a processor set.<br> +</p> +</blockquote> + +<h4>Clock Interface</h4> +<blockquote> +<p> +<a href="clock_alarm.html">clock_alarm</a> - Set up an alarm.<br> +<a href="clock_get_attributes.html">clock_get_attributes</a> - Return attributes of a clock.<br> +<a href="clock_get_time.html">clock_get_time</a> - Return the current time.<br> +<a href="clock_map_time.html">clock_map_time</a> - Return a memory object that maps a clock.<br> +<a href="clock_set_attributes.html">clock_set_attributes</a> - Set a particular clock's attributes.<br> +<a href="clock_set_time.html">clock_set_time</a> - Set the current time.<br> +<a href="clock_sleep.html">clock_sleep</a> - Delay the invoking thread until a specified time.<br> +</p> +Clock Data Structures +<p> +<a href="mapped_tvalspec.html">mapped_tvalspec</a> - Specifies the format the kernel uses to maintain a mapped clock's time.<br> +<a href="tvalspec.html">tvalspec</a> - Defines format of system time values.<br> +</p> +Clock Interface Callbacks +<p> +<a href="clock_alarm_reply.html">clock_alarm_reply</a> - Ring a preset alarm.<br> +</p> +Clock Callback Server Helpers +<p> +<a href="clock_reply_server.html"> clock_reply_server</a> - Handle kernel-generated alarm.<br> +</p> +</blockquote> + +<h4>Multi-Computer Support Interface</h4> +<blockquote> +<i> +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. +</i> +<p> +<a href="host_page_size.html">host_page_size</a> - Returns the page size for the given host.<br> +<a href="ledger_get_remote.html">ledger_get_remote</a> - Return send right to specified host's remote ledger port.<br> +<a href="ledger_set_remote.html">ledger_set_remote</a> - Set this host's remote ledger port.<br> +<a href="norma_get_special_port.html">norma_get_special_port</a> - Returns a send right for a specified node-specific special port.<br> +<a href="norma_node_self.html">norma_node_self</a> - Return the node index of the current host.<br> +<a href="norma_port_location_hint.html">norma_port_location_hint</a> - Guess a port's current location.<br> +<a href="norma_set_special_port.html">norma_set_special_port</a> - Set node-specific special port.<br> +<a href="norma_task_clone.html">norma_task_clone</a> - Create a remote task that shares access to parent task's memory.<br> +<a href="norma_task_create.html">norma_task_create</a> - Create a remote task using task_create semantics.<br> +<a href="norma_task_teleport.html">norma_task_teleport</a> - "Clone" a task on a specified node.<br> +</p> +</blockquote> + +</blockquote> + +<h3>Machine Specific Interface</h3> +<blockquote> + +<h4>Intel 386 Support</h4> +<blockquote> +<p> +<a href="i386_get_ldt.html">i386_get_ldt</a> - Returns per-thread segment descriptors from the local descriptor table (LDT).<br> +<a href="i386_io_port_add.html">i386_io_port_add</a> - Adds a device to the I/O permission bitmap for a thread. <br> +<a href="i386_io_port_list.html">i386_io_port_list</a> - Returns a list of the devices named in the thread's I/O permission bitmap.<br> +<a href="i386_io_port_remove.html">i386_io_port_remove</a> - Removes the specified device from the thread's I/O permission bitmap.<br> +<a href="i386_set_ldt.html">i386_set_ldt</a> - Allows a thread to have a private local descriptor table (LDT).<br> +</p> +</blockquote> + +<h4>PowerPC Support</h4> +<blockquote> +<p> +</p> +</blockquote> + +</blockquote> + +</BODY> + +</HTML> + diff --git a/osfmk/man/io_done_queue_create.html b/osfmk/man/io_done_queue_create.html index ee33ffffb..9fc0efd3d 100755 --- a/osfmk/man/io_done_queue_create.html +++ b/osfmk/man/io_done_queue_create.html @@ -1 +1,48 @@ -<h2>io_done_queue_create</h2> <hr> <p> <strong>Function</strong> - Create an <strong>io_done_queue</strong> kernel object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t io_done_queue_create</strong> <strong>(mach_port_t</strong> <var>host</var>, <strong>mach_port_t</strong> <var>queue</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host</var> <dd> [in host-name send right] The name (or control) port for the host on which the io_done_queue should be created. <p> <dt> <var>queue</var> <dd> [out io-done-queue send right] The port referencing the created io_done_queue. </dl> <h3>DESCRIPTION</h3> <p> The io_done_queue_create function is called to create a new instatiation of the kernel object supporting asynchronous read/write operations on a device. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> Invalid <var>host</var> parameter. <p> <dt> <strong>KERN_RESOURCE_SHORTAGE</strong> <dd> Insufficient kernel resources to allocate kernel object. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="io_done_queue_terminate.html"><strong>io_done_queue_terminate</strong></a>, <a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>, <a href="device_read_async.html"><strong>device_read_async</strong></a>, <a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, <a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, <a href="device_write_async.html"><strong>device_write_async</strong></a>, <a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>. \ No newline at end of file +<h2>io_done_queue_create</h2> +<hr> +<p> +<strong>Function</strong> - Create an <strong>io_done_queue</strong> kernel object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t io_done_queue_create</strong> + <strong>(mach_port_t</strong> <var>host</var>, + <strong>mach_port_t</strong> <var>queue</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host</var> +<dd> +[in host-name send right] The name (or control) port for the host on +which the io_done_queue should be created. +<p> +<dt> <var>queue</var> +<dd> +[out io-done-queue send right] The port referencing the created +io_done_queue. +</dl> +<h3>DESCRIPTION</h3> +<p> +The io_done_queue_create function is called to create a new +instatiation of the kernel object supporting asynchronous read/write +operations on a device. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> + Invalid <var>host</var> parameter. + <p> + <dt> <strong>KERN_RESOURCE_SHORTAGE</strong> +<dd> + Insufficient kernel resources to allocate kernel object. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="io_done_queue_terminate.html"><strong>io_done_queue_terminate</strong></a>, +<a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>, +<a href="device_read_async.html"><strong>device_read_async</strong></a>, +<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, +<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, +<a href="device_write_async.html"><strong>device_write_async</strong></a>, +<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>. diff --git a/osfmk/man/io_done_queue_terminate.html b/osfmk/man/io_done_queue_terminate.html index 67245742c..7d5f76a28 100755 --- a/osfmk/man/io_done_queue_terminate.html +++ b/osfmk/man/io_done_queue_terminate.html @@ -1 +1,41 @@ -<h2>io_done_queue_terminate</h2> <hr> <p> <strong>Function</strong> - Terminate an io_done_queue kernel object. <h3>SYNOPSIS</h3> <pre> <strong>#include<device/device.h></strong> <strong>kern_return_t io_done_queue_terminate</strong> <strong>(mach_port_t</strong> <var>queue</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>queue</var> <dd> [in io-done-queue send right] The port referencing the <strong>io_done_queue</strong> to be destroyed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>io_done_queue_terminate</strong> function is called to destroy a previous instatiation of the kernel object supporting asynchronous read/write operations on a device. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> Invalid <var>queue</var> parameter. <p> </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>, <a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>, <a href="device_read_async.html"><strong>device_read_async</strong></a>, <a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, <a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, <a href="device_write_async.html"><strong>device_write_async</strong></a>, <a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>. \ No newline at end of file +<h2>io_done_queue_terminate</h2> +<hr> +<p> +<strong>Function</strong> - Terminate an io_done_queue kernel object. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<device/device.h></strong> + +<strong>kern_return_t io_done_queue_terminate</strong> + <strong>(mach_port_t</strong> <var>queue</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>queue</var> +<dd> +[in io-done-queue send right] The port referencing the <strong>io_done_queue</strong> +to be destroyed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>io_done_queue_terminate</strong> function is called to destroy a previous +instatiation of the kernel object supporting asynchronous read/write +operations on a device. +<h3>RETURN VALUES</h3> +<dl> + <dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> + Invalid <var>queue</var> parameter. + <p> +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>, +<a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>, +<a href="device_read_async.html"><strong>device_read_async</strong></a>, +<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, +<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, +<a href="device_write_async.html"><strong>device_write_async</strong></a>, +<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>. diff --git a/osfmk/man/io_done_queue_wait.html b/osfmk/man/io_done_queue_wait.html index 494c06c23..a266cce1f 100755 --- a/osfmk/man/io_done_queue_wait.html +++ b/osfmk/man/io_done_queue_wait.html @@ -1 +1,61 @@ -<h2>io_done_queue_wait</h2> <hr> <p> <strong>System Trap</strong> - Wait on an io_done_queue kernel object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t io_done_queue_wait</strong> <strong>(mach_port_t</strong> <var>queue</var>, <strong>io_done_result_t</strong> <var>*result</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>queue</var> <dd> [in io-done-queue send right] The port referencing the io_done_queue to be destroyed. <p> <dt> <var>result</var> <dd> [out structure] The data structure to be filled in with the completion status of the I/O operation. </dl> <h3>DESCRIPTION</h3> <p> The <strong>io_done_queue_wait</strong> interface is called to obtain the results of a previously requested asynchronous I/O operation. For each <strong>io_done_queue_wait</strong> invocation, the status of one I/O request is returned. If there are no pending I/O completions, io_done_queue_wait blocks in the kernel on the address of the completion queue. The mKernel, from interrupt context, enqueues (in FIFO order) completions (struct <strong>io_done_result</strong>'s) on the completion queue and posts a wakeup on the queue for each I/O completion. Completion processing previously done by the mKernel <strong>io_done thread</strong> is now done by the task thread when it awakens. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_TERMINATED</strong> <dd> Stale <strong>io_done_queue</strong> handle. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> Invalid <var>queue</var> parameter. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The <var>result</var> parameter is a bad address. <p> </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>, <a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>, <a href="device_read_async.html"><strong>device_read_async</strong></a>, <a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, <a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, <a href="device_write_async.html"><strong>device_write_async</strong></a>, <a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>. \ No newline at end of file +<h2>io_done_queue_wait</h2> +<hr> +<p> +<strong>System Trap</strong> - Wait on an io_done_queue kernel object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t io_done_queue_wait</strong> + <strong>(mach_port_t</strong> <var>queue</var>, + <strong>io_done_result_t</strong> <var>*result</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>queue</var> +<dd> +[in io-done-queue send right] The port referencing the io_done_queue +to be destroyed. +<p> +<dt> <var>result</var> +<dd> +[out structure] The data structure to be filled in with the completion +status of the I/O operation. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>io_done_queue_wait</strong> interface is called to obtain the results of a +previously requested asynchronous I/O operation. For each +<strong>io_done_queue_wait</strong> invocation, the status of one I/O request is +returned. If there are no pending I/O completions, io_done_queue_wait +blocks in the kernel on the address of the completion queue. The +mKernel, from interrupt context, enqueues (in FIFO order) completions +(struct <strong>io_done_result</strong>'s) on the completion queue and posts a wakeup +on the queue for each I/O completion. Completion processing previously +done by the mKernel <strong>io_done thread</strong> is now done by the task thread when +it awakens. +<h3>RETURN VALUES</h3> +<dl> + <dt> <strong>KERN_TERMINATED</strong> +<dd> + Stale <strong>io_done_queue</strong> handle. + <p> + + <dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> + Invalid <var>queue</var> parameter. + <p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> + The <var>result</var> parameter is a bad address. + <p> +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>, +<a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>, +<a href="device_read_async.html"><strong>device_read_async</strong></a>, +<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>, +<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>, +<a href="device_write_async.html"><strong>device_write_async</strong></a>, +<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>. diff --git a/osfmk/man/kernel_resource_sizes.html b/osfmk/man/kernel_resource_sizes.html index 0404ab2ea..0f9c035fb 100755 --- a/osfmk/man/kernel_resource_sizes.html +++ b/osfmk/man/kernel_resource_sizes.html @@ -1 +1,50 @@ -<h2>kernel_resource_sizes</h2> <hr> <p> <strong>Structure</strong> - Used to present the sizes of kernel's major structures. <h3>SYNOPSIS</h3> <pre> <strong>struct kernel_resource_sizes</strong> <strong>{</strong> <strong>vm_size_t</strong> <var>task</var><strong>;</strong> <strong>vm_size_t</strong> <var>thread</var><strong>;</strong> <strong>vm_size_t</strong> <var>port</var><strong>;</strong> <strong>vm_size_t</strong> <var>memory_region</var><strong>;</strong> <strong>vm_size_t</strong> <var>memory_object</var><strong>;</strong> <strong>};</strong> <strong>typedef struct kernel_resource_sizes* kernel_resource_sizes_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>task</var> <dd> Space consumed by an empty task. <p> <dt> <var>thread</var> <dd> Space consumed by a thread. <p> <dt> <var>port</var> <dd> Space consumed by a port with an empty message queue. <p> <dt> <var>memory_region</var> <dd> Space consumed by each distinct memory region (as reported by <strong>vm_region</strong>) in a task's address space. <p> <dt> <var>memory_object</var> <dd> Space consumed to manage a memory object with no resident pages or copy objects. </dl> <h3>DESCRIPTION</h3> <p> The <strong>kernel_resource_sizes</strong> structure defines the sizes of significant kernel structures. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_info.html"><strong>host_info</strong></a>. \ No newline at end of file +<h2>kernel_resource_sizes</h2> +<hr> +<p> +<strong>Structure</strong> - Used to present the sizes of kernel's major structures. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct kernel_resource_sizes</strong> +<strong>{</strong> + <strong>vm_size_t</strong> <var>task</var><strong>;</strong> + <strong>vm_size_t</strong> <var>thread</var><strong>;</strong> + <strong>vm_size_t</strong> <var>port</var><strong>;</strong> + <strong>vm_size_t</strong> <var>memory_region</var><strong>;</strong> + <strong>vm_size_t</strong> <var>memory_object</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct kernel_resource_sizes* kernel_resource_sizes_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>task</var> +<dd> +Space consumed by an empty task. +<p> +<dt> <var>thread</var> +<dd> +Space consumed by a thread. +<p> +<dt> <var>port</var> +<dd> +Space consumed by a port with an empty message queue. +<p> +<dt> <var>memory_region</var> +<dd> +Space consumed by each distinct memory region (as reported by +<strong>vm_region</strong>) in a task's address space. +<p> +<dt> <var>memory_object</var> +<dd> +Space consumed to manage a memory object with no resident pages or +copy objects. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>kernel_resource_sizes</strong> structure defines the sizes +of significant kernel +structures. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_info.html"><strong>host_info</strong></a>. diff --git a/osfmk/man/ledger_create.html b/osfmk/man/ledger_create.html index 6971798f0..3a4030443 100755 --- a/osfmk/man/ledger_create.html +++ b/osfmk/man/ledger_create.html @@ -1 +1,69 @@ -<h2>ledger_create</h2> <hr> <p> <strong>Function</strong> - Create a subordinate ledger. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t ledger_create</strong> <strong>(ledger_port_t</strong> <var>parent_ledger</var>, <strong>ledger_port_t</strong> <var>ledger_ledger</var>, <strong>ledger_port_t</strong> <var>child_ledger</var>, <strong>ledger_item_t</strong> <var>transfer</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>parent_ledger</var> <dd> [in ledger send right] The parent ledger. <p> <dt> <var>ledger_ledger</var> <dd> [in ledger send right] The wired kernel memory ledger providing the space from which the ledger itself is drawn. <p> <dt> <var>child_ledger</var> <dd> [out ledger send right] The new child ledger, of the same resource type as the parent ledger. <p> <dt> <var>transfer</var> <dd> [in scalar] The resource amount to transfer to the new ledger. </dl> <h3>DESCRIPTION</h3> <p> The <strong>ledger_create</strong> function creates a subordinate ledger. Resource limits can be transferred from the parent ledger. The child ledger itself is accounted against the <var>ledger_ledger</var>. A new ledger inherits the remote service port. <h3>NOTES</h3> <p> This interface is not implemented in OSF/1 R1.3. <p> A ledger limit of <strong>LEDGER_ITEM_INFINITE</strong> allows any amount (even infinity) to be withdrawn. The root ledger has such a limit. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_RESOURCE_SHORTAGE</strong> <dd> Transferring the resources would cause the parent ledger to exceed its limits. <p> <dt> <strong>KERN_INVALID_LEDGER</strong> <dd> <var>ledger_ledger</var> is not a wired kernel memory ledger. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>, <a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>, <a href="ledger_read.html"><strong>ledger_read</strong></a>, <a href="ledger_set_remote.html"><strong>ledger_set_remote</strong></a>. \ No newline at end of file +<h2>ledger_create</h2> +<hr> +<p> +<strong>Function</strong> - Create a subordinate ledger. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t ledger_create</strong> + <strong>(ledger_port_t</strong> <var>parent_ledger</var>, + <strong>ledger_port_t</strong> <var>ledger_ledger</var>, + <strong>ledger_port_t</strong> <var>child_ledger</var>, + <strong>ledger_item_t</strong> <var>transfer</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>parent_ledger</var> +<dd> +[in ledger send right] +The parent ledger. +<p> +<dt> <var>ledger_ledger</var> +<dd> +[in ledger send right] +The wired kernel memory ledger providing the +space from which the ledger itself is drawn. +<p> +<dt> <var>child_ledger</var> +<dd> +[out ledger send right] +The new child ledger, of the same resource type +as the parent ledger. +<p> +<dt> <var>transfer</var> +<dd> +[in scalar] +The resource amount to transfer to the new ledger. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>ledger_create</strong> function creates a subordinate ledger. +Resource limits can be +transferred from the parent ledger. The child ledger itself +is accounted against +the <var>ledger_ledger</var>. A new ledger inherits the remote service port. +<h3>NOTES</h3> +<p> +This interface is not implemented in OSF/1 R1.3. +<p> +A ledger limit of <strong>LEDGER_ITEM_INFINITE</strong> allows any amount (even +infinity) to be withdrawn. The root ledger has such a limit. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_RESOURCE_SHORTAGE</strong> +<dd> +Transferring the resources would cause the parent ledger to exceed its +limits. +<p> +<dt> <strong>KERN_INVALID_LEDGER</strong> +<dd> +<var>ledger_ledger</var> is not a wired kernel memory ledger. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>, +<a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>, +<a href="ledger_read.html"><strong>ledger_read</strong></a>, +<a href="ledger_set_remote.html"><strong>ledger_set_remote</strong></a>. diff --git a/osfmk/man/ledger_get_remote.html b/osfmk/man/ledger_get_remote.html index 7b9a49315..58abf486e 100755 --- a/osfmk/man/ledger_get_remote.html +++ b/osfmk/man/ledger_get_remote.html @@ -1 +1,80 @@ -<h2>ledger_get_remote</h2> <hr> <p> <strong>Function</strong> - Return send right to specified host's remote ledger port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t ledger_get_remote</strong> <strong>(ledger_port_t</strong> <var>ledger</var>, <strong>host_t</strong> <var>host_name</var>, <strong>ledger</strong> <var>service_port</var><strong>);</strong> <strong>kern_return_t ledger_return_remote</strong> <strong>(ledger_port_t</strong> <var>ledger</var>, <strong>host_t</strong> <var>host_name</var>, <strong>ledger</strong> <var>service_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>ledger</var> <dd> [in ledger send right] The ledger whose service port is desired. <p> <dt> <var>host_name</var> <dd> [in host-name send right] The name for the host requesting the service port. <p> <dt> <var>service_port</var> <dd> [out ledger-service send right] The ledger service port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>ledger_get_remote</strong> function returns the remote ledger service port for the ledger <h3>NOTES</h3> <p> This interface is not implemented in OSF/1 R1.3. <p> This mechanism supports distributed resource ledgers in the following way: <dl> <dd> With <strong>ledger_set_remote</strong>, a ledger is assigned a remote ledger service port. <dd> This ledger is used as the ledger for a create operation. If the ledger is local to the target kernel, all is fine. <dd> For a non-local creation, the target kernel sees that the supplied ledger is not a local ledger. The kernel sends a <strong>ledger_get_remote</strong> message to it, including the host name. <dd> The (remote) ledger receives this message, ignores the host name and returns the remote ledger service port. <dd> Assuming that the remote ledger service port is not a local ledger, the kernel sends a <strong>ledger_get_remote</strong> message to this service port. <dd> A server receives this request (with the <strong>ledger_return_remote</strong> server interface) and uses the identity of the service port as well as the host name of the target kernel to locate or create a suitable ledger on that kernel. <dd> The port for a ledger on the target kernel is sent to that kernel and used. </dl> <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="ledger_create.html"><strong>ledger_create</strong></a>, <a href="ledger_set_remote.html"><strong>ledger_set_remote</strong></a>. \ No newline at end of file +<h2>ledger_get_remote</h2> +<hr> +<p> +<strong>Function</strong> - Return send right to specified host's remote ledger port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t ledger_get_remote</strong> + <strong>(ledger_port_t</strong> <var>ledger</var>, + <strong>host_t</strong> <var>host_name</var>, + <strong>ledger</strong> <var>service_port</var><strong>);</strong> + + +<strong>kern_return_t ledger_return_remote</strong> + <strong>(ledger_port_t</strong> <var>ledger</var>, + <strong>host_t</strong> <var>host_name</var>, + <strong>ledger</strong> <var>service_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>ledger</var> +<dd> +[in ledger send right] +The ledger whose service port is desired. +<p> +<dt> <var>host_name</var> +<dd> +[in host-name send right] +The name for the host requesting the service +port. +<p> +<dt> <var>service_port</var> +<dd> +[out ledger-service send right] +The ledger service port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>ledger_get_remote</strong> function returns the remote ledger +service port for the +ledger +<h3>NOTES</h3> +<p> +This interface is not implemented in OSF/1 R1.3. +<p> +This mechanism supports distributed resource ledgers in the following way: +<dl> +<dd> +With <strong>ledger_set_remote</strong>, a ledger is assigned a remote +ledger service port. +<dd> +This ledger is used as the ledger for a create operation. +If the ledger is local to the target kernel, all is fine. +<dd> +For a non-local creation, the target kernel sees that the supplied +ledger is not +a local ledger. The kernel sends a <strong>ledger_get_remote</strong> message to it, +including the host name. +<dd> +The (remote) ledger receives this message, ignores the host name and returns +the remote ledger service port. +<dd> +Assuming that the remote ledger service port is not a local ledger, the kernel +sends a <strong>ledger_get_remote</strong> message to this service port. +<dd> +A server receives this request (with the <strong>ledger_return_remote</strong> +server interface) +and uses the identity of the service port as well as the host name of the +target kernel to locate or create a suitable ledger on that kernel. +<dd> +The port for a ledger on the target kernel is sent to that kernel and used. +</dl> +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="ledger_create.html"><strong>ledger_create</strong></a>, +<a href="ledger_set_remote.html"><strong>ledger_set_remote</strong></a>. diff --git a/osfmk/man/ledger_read.html b/osfmk/man/ledger_read.html index fa283565a..17ff288e3 100755 --- a/osfmk/man/ledger_read.html +++ b/osfmk/man/ledger_read.html @@ -1 +1,47 @@ -<h2>ledger_read</h2> <hr> <p> <strong>Function</strong> - Return the ledger limit and balance. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t ledger_read</strong> <strong>(ledger_port_t</strong> <var>ledger</var>, <strong>ledger_item_t</strong> <var>balance</var>, <strong>ledger_item_t</strong> <var>maximum</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>ledger</var> <dd> [in ledger send right] The ledger to read <p> <dt> <var>balance</var> <dd> [out scalar] The current usage <p> <dt> <var>maximum</var> <dd> [out scalar] The resource limit </dl> <h3>DESCRIPTION</h3> <p> The <strong>ledger_read</strong> function returns the current balance and limit in a ledger. <h3>NOTES</h3> <p> This interface is not implemented in OSF/1 R1.3. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="ledger_create.html"><strong>ledger_create</strong></a>, <a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>, <a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>. \ No newline at end of file +<h2>ledger_read</h2> +<hr> +<p> +<strong>Function</strong> - Return the ledger limit and balance. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t ledger_read</strong> + <strong>(ledger_port_t</strong> <var>ledger</var>, + <strong>ledger_item_t</strong> <var>balance</var>, + <strong>ledger_item_t</strong> <var>maximum</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>ledger</var> +<dd> +[in ledger send right] +The ledger to read +<p> +<dt> <var>balance</var> +<dd> +[out scalar] +The current usage +<p> +<dt> <var>maximum</var> +<dd> +[out scalar] +The resource limit +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>ledger_read</strong> function returns the current balance +and limit in a ledger. +<h3>NOTES</h3> +<p> +This interface is not implemented in OSF/1 R1.3. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="ledger_create.html"><strong>ledger_create</strong></a>, +<a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>, +<a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>. + + diff --git a/osfmk/man/ledger_set_remote.html b/osfmk/man/ledger_set_remote.html index 43a4edb1f..d76bbb1a4 100755 --- a/osfmk/man/ledger_set_remote.html +++ b/osfmk/man/ledger_set_remote.html @@ -1 +1,39 @@ -<h2>ledger_set_remote</h2> <hr> <p> <strong>Function</strong> - Set this host's remote ledger port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t ledger_set_remote</strong> <strong>(ledger_port_t</strong> <var>ledger</var>, <strong>ledger_port_t</strong> <var>service_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>ledger</var> <dd> [in ledger send right] The ledger whose service port is to be set. <p> <dt> <var>service_port</var> <dd> [in ledger-service send right] The ledger service port </dl> <h3>DESCRIPTION</h3> <p> The <strong>ledger_set_remote</strong> function sets the remote ledger service port for the ledger. This is the port the ledger will return for <strong>ledger_get_remote</strong> requests. <h3>NOTES</h3> <p> This interface is not implemented in OSF/1 R1.3. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="ledger_create.html"><strong>ledger_create</strong></a>, <a href="ledger_get_remote.html"><strong>ledger_get_remote</strong></a>. \ No newline at end of file +<h2>ledger_set_remote</h2> +<hr> +<p> +<strong>Function</strong> - Set this host's remote ledger port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t ledger_set_remote</strong> + <strong>(ledger_port_t</strong> <var>ledger</var>, + <strong>ledger_port_t</strong> <var>service_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>ledger</var> +<dd> +[in ledger send right] +The ledger whose service port is to be set. +<p> +<dt> <var>service_port</var> +<dd> +[in ledger-service send right] +The ledger service port +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>ledger_set_remote</strong> function sets the remote ledger service port +for the ledger. This is the port the ledger will return for +<strong>ledger_get_remote</strong> requests. +<h3>NOTES</h3> +<p> +This interface is not implemented in OSF/1 R1.3. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="ledger_create.html"><strong>ledger_create</strong></a>, +<a href="ledger_get_remote.html"><strong>ledger_get_remote</strong></a>. diff --git a/osfmk/man/ledger_terminate.html b/osfmk/man/ledger_terminate.html index a8dd384fd..1029baa00 100755 --- a/osfmk/man/ledger_terminate.html +++ b/osfmk/man/ledger_terminate.html @@ -1 +1,35 @@ -<h2>ledger_terminate</h2> <hr> <p> <strong>Function</strong> - Destroy a ledger. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t ledger_terminate</strong> <strong>(ledger_port_t</strong> <var>ledger</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>ledger</var> <dd> [in ledger send right] The ledger to destroy </dl> <h3>DESCRIPTION</h3> <p> The <strong>ledger_terminate</strong> function destroys a ledger. All resources drawn from this ledger will also be destroyed. The resource limits in the ledger are returned to the ledger's parent. <h3>NOTES</h3> <p> This interface is not implemented in OSF/1 R1.3. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="ledger_create.html"><strong>ledger_create</strong></a>, <a href="ledger_read.html"><strong>ledger_read</strong></a>, <a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>. \ No newline at end of file +<h2>ledger_terminate</h2> +<hr> +<p> +<strong>Function</strong> - Destroy a ledger. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t ledger_terminate</strong> + <strong>(ledger_port_t</strong> <var>ledger</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>ledger</var> +<dd> +[in ledger send right] +The ledger to destroy +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>ledger_terminate</strong> function destroys a ledger. All +resources drawn from this +ledger will also be destroyed. The resource limits in the ledger +are returned to the ledger's parent. +<h3>NOTES</h3> +<p> +This interface is not implemented in OSF/1 R1.3. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="ledger_create.html"><strong>ledger_create</strong></a>, +<a href="ledger_read.html"><strong>ledger_read</strong></a>, +<a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>. diff --git a/osfmk/man/ledger_transfer.html b/osfmk/man/ledger_transfer.html index 60676a29c..c703d50da 100755 --- a/osfmk/man/ledger_transfer.html +++ b/osfmk/man/ledger_transfer.html @@ -1 +1,51 @@ -<h2>ledger_transfer</h2> <hr> <p> <strong>Function</strong> - Transfer resources from a parent ledger to a child. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t ledger_transfer</strong> <strong>(ledger_port_t</strong> <var>parent_ledger</var>, <strong>ledger_port_t</strong> <var>child_ledger</var>, <strong>ledger_item_t</strong> <var>transfer</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>parent_ledger</var> <dd> [in ledger send right] The parent ledger <p> <dt> <var>child_ledger</var> <dd> [in ledger send right] The child ledger <p> <dt> <var>transfer</var> <dd> [in scalar] The resource amount to transfer. A positive amount moves the resource allocation from the parent to the child; a negative amount moves the reverse. </dl> <h3>DESCRIPTION</h3> <p> The <strong>ledger_transfer</strong> function transfers resources from a parent to a child ledger. <h3>NOTES</h3> <p> This interface is not implemented in OSF/1 R1.3. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_RESOURCE_SHORTAGE</strong> <dd> Transferring the resources would cause one ledger to exceed its limit. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="ledger_create.html"><strong>ledger_create</strong></a>, <a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>, <a href="ledger_read.html"><strong>ledger_read</strong></a>. \ No newline at end of file +<h2>ledger_transfer</h2> +<hr> +<p> +<strong>Function</strong> - Transfer resources from a parent ledger to a child. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t ledger_transfer</strong> + <strong>(ledger_port_t</strong> <var>parent_ledger</var>, + <strong>ledger_port_t</strong> <var>child_ledger</var>, + <strong>ledger_item_t</strong> <var>transfer</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>parent_ledger</var> +<dd> +[in ledger send right] +The parent ledger +<p> +<dt> <var>child_ledger</var> +<dd> +[in ledger send right] +The child ledger +<p> +<dt> <var>transfer</var> +<dd> +[in scalar] +The resource amount to transfer. A positive amount moves +the resource allocation from the parent to the child; a negative amount +moves the reverse. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>ledger_transfer</strong> function transfers resources from +a parent to a child ledger. +<h3>NOTES</h3> +<p> +This interface is not implemented in OSF/1 R1.3. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_RESOURCE_SHORTAGE</strong> +<dd> +Transferring the resources would cause one ledger to exceed its limit. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="ledger_create.html"><strong>ledger_create</strong></a>, +<a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>, +<a href="ledger_read.html"><strong>ledger_read</strong></a>. diff --git a/osfmk/man/lock_acquire.html b/osfmk/man/lock_acquire.html index 7bfc0f91f..5181b482a 100755 --- a/osfmk/man/lock_acquire.html +++ b/osfmk/man/lock_acquire.html @@ -1 +1,61 @@ -<h2>lock_acquire</h2> <hr> <p> <strong>Function</strong> - Acquire access rights to a lock. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t lock_acquire</strong> <strong>(lock_set_t</strong> <var>lock_set</var>, <strong>int</strong> <var>lock_id</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>lock_set</var> <dd> [in send right] The port naming the lock set which represents the lock. <p> <dt> <var>lock_id</var> <dd> [in scalar] The lock, represented by the lock set, to be acquired. </dl> <h3>DESCRIPTION</h3> <p> The <strong>lock_acquire</strong> function acquires access rights to a specific lock being represented by a given lock set. If the lock is already controlled by another thread then the calling thread will block. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The lock was acquired. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified lock set is invalid, or the lock id is out of range. <p> <dt> <strong>KERN_LOCK_UNSTABLE</strong> <dd> The acquired lock has an unstable state. <p> <dt> <strong>KERN_LOCK_SET_DESTROYED</strong> <dd> The specified lock has been destroyed. <p> <dt> <strong>KERN_ABORTED</strong> <dd> While blocked to wait for the specified lock to become available, the calling thread was awoken by an unrelated event, such as thread termination. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="lock_release.html"><strong>lock_release</strong></a>, <a href="lock_try.html"><strong>lock_try</strong></a>, <a href="lock_handoff.html"><strong>lock_handoff</strong></a>, <a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, <a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, <a href="lock_set_create.html"><strong>lock_set_create</strong></a>, <a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. \ No newline at end of file +<h2>lock_acquire</h2> +<hr> +<p> +<strong>Function</strong> - Acquire access rights to a lock. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t lock_acquire</strong> + <strong>(lock_set_t</strong> <var>lock_set</var>, + <strong>int</strong> <var>lock_id</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>lock_set</var> +<dd> +[in send right] The port naming the lock set which represents the +lock. +<p> +<dt> <var>lock_id</var> +<dd> +[in scalar] The lock, represented by the lock set, to be acquired. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>lock_acquire</strong> function acquires access rights to a specific lock +being represented by a given lock set. If the lock is already +controlled by another thread then the calling thread will block. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The lock was acquired. +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The specified lock set is invalid, or the lock id is out of range. +<p> +<dt> <strong>KERN_LOCK_UNSTABLE</strong> +<dd> +The acquired lock has an unstable state. + <p> +<dt> <strong>KERN_LOCK_SET_DESTROYED</strong> +<dd> +The specified lock has been destroyed. +<p> +<dt> <strong>KERN_ABORTED</strong> +<dd> +While blocked to wait for the specified lock to become available, the calling + thread was awoken by an unrelated event, such as thread termination. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="lock_release.html"><strong>lock_release</strong></a>, +<a href="lock_try.html"><strong>lock_try</strong></a>, +<a href="lock_handoff.html"><strong>lock_handoff</strong></a>, +<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, +<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, +<a href="lock_set_create.html"><strong>lock_set_create</strong></a>, +<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. diff --git a/osfmk/man/lock_handoff.html b/osfmk/man/lock_handoff.html index 9c6e84b87..aed2ed9ad 100755 --- a/osfmk/man/lock_handoff.html +++ b/osfmk/man/lock_handoff.html @@ -1 +1,63 @@ -<h2>lock_handoff</h2> <hr> <p> <strong>Function</strong> - Hand-off ownership of a lock. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t lock_handoff</strong> <strong>(lock_set_t</strong> <var>lock_set</var>, <strong>int</strong> <var>lock_id</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>lock_set</var> <dd> [in send right] The port naming the lock set which represents the lock. <p> <dt> <var>lock_id</var> <dd> [in scalar] The lock, represented by the lock set, to be handed off. </dl> <h3>DESCRIPTION</h3> <p> The <strong>lock_handoff</strong> function passes lock ownership from the calling thread to an anonymous accepting thread. The lock must be owned by the calling thread. If the accepting thread is not waiting to receive the lock, the calling thread will block until the hand-off is accepted. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified lock_set is invalid, or the lock_id is out of range. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> The calling thread does not own the lock being handed off. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The lock hand-off was successful. <p> <dt> <strong>KERN_LOCK_SET_DESTROYED</strong> <dd> The specified lock has been destroyed. <p> <dt> <strong>KERN_ABORTED</strong> <dd> While blocked to wait for the accepting thread to assume the lock's ownership, the calling thread was awoken by an unrelated event; the lock's handoff state is cleared. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="lock_acquire.html"><strong>lock_acquire</strong></a>, <a href="lock_release.html"><strong>lock_release</strong></a>, <a href="lock_try.html"><strong>lock_try</strong></a>, <a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, <a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, <a href="lock_set_create.html"><strong>lock_set_create</strong></a>, <a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. \ No newline at end of file +<h2>lock_handoff</h2> +<hr> +<p> +<strong>Function</strong> - Hand-off ownership of a lock. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t lock_handoff</strong> + <strong>(lock_set_t</strong> <var>lock_set</var>, + <strong>int</strong> <var>lock_id</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>lock_set</var> +<dd> +[in send right] The port naming the lock set which represents the +lock. +<p> +<dt> <var>lock_id</var> +<dd> +[in scalar] The lock, represented by the lock set, to be handed off. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>lock_handoff</strong> function passes lock ownership from the calling +thread to an anonymous accepting thread. The lock must be owned by the +calling thread. If the accepting thread is not waiting to receive the +lock, the calling thread will block until the hand-off is accepted. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The specified lock_set is invalid, or the lock_id is out of range. +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +The calling thread does not own the lock being handed off. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The lock hand-off was successful. +<p> +<dt> <strong>KERN_LOCK_SET_DESTROYED</strong> +<dd> +The specified lock has been destroyed. +<p> +<dt> <strong>KERN_ABORTED</strong> +<dd> +While blocked to wait for the accepting thread to assume the lock's ownership, + the calling thread was awoken by an unrelated event; + the lock's handoff state is cleared. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="lock_acquire.html"><strong>lock_acquire</strong></a>, +<a href="lock_release.html"><strong>lock_release</strong></a>, +<a href="lock_try.html"><strong>lock_try</strong></a>, +<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, +<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, +<a href="lock_set_create.html"><strong>lock_set_create</strong></a>, +<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. diff --git a/osfmk/man/lock_handoff_accept.html b/osfmk/man/lock_handoff_accept.html index 21519d2fd..87dd52287 100755 --- a/osfmk/man/lock_handoff_accept.html +++ b/osfmk/man/lock_handoff_accept.html @@ -1 +1,66 @@ -<h2>lock_handoff_accept</h2> <hr> <p> <strong>Function</strong> - Accept a lock hand-off. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t lock_handoff_accept</strong> <strong>(lock_set_t</strong> <var>lock_set</var>, <strong>int</strong> <var>lock_id</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>lock_set</var> <dd> [in send right] The port naming the lock set which represents the lock. <p> <dt> <var>lock_id</var> <dd> [in scalar] The lock, represented by the lock set, that is the object of the handoff operation. </dl> <h3>DESCRIPTION</h3> <p> The <strong>lock_handoff_accept</strong> function accepts a lock hand-off from an anonymous sending thread. If the sending thread is not waiting to hand-off the lock, the calling thread will block until the lock handoff is completed. Only one thread may be waiting to accept a lock handoff at any given time. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_ALREADY_WAITING</strong> <dd> Another thread is already waiting for a hand-off of this lock. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified lock_set is invalid, or the lock_id is out of range. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The lock hand-off was successful. <p> <dt> <strong>KERN_LOCK_UNSTABLE</strong> <dd> The acquired lock has an unstable state. <p> <dt> <strong>KERN_LOCK_SET_DESTROYED</strong> <dd> The specified lock has been destroyed. <p> <dt> <strong>KERN_ABORTED</strong> <dd> While blocked to wait for the sending thread to transfer the lock's ownership, the calling thread was awoken by an unrelated event; the lock's handoff state is cleared. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="lock_acquire.html"><strong>lock_acquire</strong></a>, <a href="lock_release.html"><strong>lock_release</strong></a>, <a href="lock_try.html"><strong>lock_try</strong></a>, <a href="lock_handoff.html"><strong>lock_handoff</strong></a>. \ No newline at end of file +<h2>lock_handoff_accept</h2> +<hr> +<p> +<strong>Function</strong> - Accept a lock hand-off. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t lock_handoff_accept</strong> + <strong>(lock_set_t</strong> <var>lock_set</var>, + <strong>int</strong> <var>lock_id</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>lock_set</var> +<dd> +[in send right] The port naming the lock set which represents the +lock. +<p> +<dt> <var>lock_id</var> +<dd> +[in scalar] The lock, represented by the lock set, that is the object +of the handoff operation. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>lock_handoff_accept</strong> function accepts a lock +hand-off from an anonymous sending thread. If the sending thread is +not waiting to hand-off the lock, the calling thread will block until +the lock handoff is completed. Only one thread may be waiting to +accept a lock handoff at any given time. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_ALREADY_WAITING</strong> +<dd> +Another thread is already waiting for a hand-off of this lock. +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The specified lock_set is invalid, or the lock_id is out of range. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The lock hand-off was successful. +<p> +<dt> <strong>KERN_LOCK_UNSTABLE</strong> +<dd> +The acquired lock has an unstable state. +<p> +<dt> <strong>KERN_LOCK_SET_DESTROYED</strong> +<dd> +The specified lock has been destroyed. +<p> +<dt> <strong>KERN_ABORTED</strong> +<dd> +While blocked to wait for the sending thread to transfer the lock's ownership, + the calling thread was awoken by an unrelated event; + the lock's handoff state is cleared. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="lock_acquire.html"><strong>lock_acquire</strong></a>, +<a href="lock_release.html"><strong>lock_release</strong></a>, +<a href="lock_try.html"><strong>lock_try</strong></a>, +<a href="lock_handoff.html"><strong>lock_handoff</strong></a>. diff --git a/osfmk/man/lock_make_stable.html b/osfmk/man/lock_make_stable.html index 53a306df6..3170d7c65 100755 --- a/osfmk/man/lock_make_stable.html +++ b/osfmk/man/lock_make_stable.html @@ -1 +1,55 @@ -<h2>lock_make_stable</h2> <hr> <p> <strong>Function</strong> - Stabilize the state of the specified lock. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t lock_make_stable</strong> <strong>(lock_set_t</strong> <var>lock_set</var>, <strong>int</strong> <var>lock_id</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>lock_set</var> <dd> [in send right] The port naming the lock set which represents the lock. <p> <dt> <var>lock_id</var> <dd> [in scalar] The lock, represented by the lock set, to be stabilized. </dl> <h3>DESCRIPTION</h3> <p> The <strong>lock_make_stable</strong> function clears the specified lock's unstable state, making the lock's state stable again. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified lock set is invalid, or the lock id is out of range. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> The caller does not own the specified lock. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The lock's state was stabilized. <p> <dt> <strong>KERN_LOCK_SET_DESTROYED</strong> <dd> The specified lock has been destroyed. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="lock_acquire.html"><strong>lock_acquire</strong></a>, <a href="lock_release.html"><strong>lock_release</strong></a>, <a href="lock_try.html"><strong>lock_try</strong></a>, <a href="lock_handoff.html"><strong>lock_handoff</strong></a>, <a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, <a href="lock_set_create.html"><strong>lock_set_create</strong></a>, <a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. \ No newline at end of file +<h2>lock_make_stable</h2> +<hr> +<p> +<strong>Function</strong> - Stabilize the state of the specified lock. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t lock_make_stable</strong> + <strong>(lock_set_t</strong> <var>lock_set</var>, + <strong>int</strong> <var>lock_id</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>lock_set</var> +<dd> +[in send right] The port naming the lock set which represents the +lock. +<p> +<dt> <var>lock_id</var> +<dd> +[in scalar] The lock, represented by the lock set, to be stabilized. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>lock_make_stable</strong> function clears the specified lock's unstable +state, making the lock's state stable again. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The specified lock set is invalid, or the lock id is out of range. + <p> + <dt> <strong>KERN_INVALID_RIGHT</strong> + <dd> + The caller does not own the specified lock. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The lock's state was stabilized. +<p> +<dt> <strong>KERN_LOCK_SET_DESTROYED</strong> +<dd> +The specified lock has been destroyed. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="lock_acquire.html"><strong>lock_acquire</strong></a>, +<a href="lock_release.html"><strong>lock_release</strong></a>, +<a href="lock_try.html"><strong>lock_try</strong></a>, +<a href="lock_handoff.html"><strong>lock_handoff</strong></a>, +<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, +<a href="lock_set_create.html"><strong>lock_set_create</strong></a>, +<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. diff --git a/osfmk/man/lock_release.html b/osfmk/man/lock_release.html index 2fc3d3f13..36a6ef30d 100755 --- a/osfmk/man/lock_release.html +++ b/osfmk/man/lock_release.html @@ -1 +1,55 @@ -<h2>lock_release</h2> <hr> <p> <strong>Function</strong> - Release ownership of a lock. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t lock_release</strong> <strong>(lock_set_t</strong> <var>lock_set</var>, <strong>int</strong> <var>lock_id</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>lock_set</var> <dd> [in send right] The port naming the lock set which represents the lock. <p> <dt> <var>lock_id</var> <dd> [in scalar] The lock, represented by the lock set, to be released. </dl> <h3>DESCRIPTION</h3> <p> The <strong>lock_release</strong> function release the ownership of the specified lock. If the calling thread does not own the lock then the call will fail. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified lock_set is invalid, or the lock_id is out of range. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> The specified task does not own the specified lock. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The ownership of the lock was released. <p> <dt> <strong>KERN_LOCK_SET_DESTROYED</strong> <dd> The specified lock has been destroyed. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="lock_acquire.html"><strong>lock_acquire</strong></a>, <a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, <a href="lock_try.html"><strong>lock_try</strong></a>, <a href="lock_handoff.html"><strong>lock_handoff</strong></a>, <a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, <a href="lock_set_create.html"><strong>lock_set_create</strong></a>, <a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. \ No newline at end of file +<h2>lock_release</h2> +<hr> +<p> +<strong>Function</strong> - Release ownership of a lock. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t lock_release</strong> + <strong>(lock_set_t</strong> <var>lock_set</var>, + <strong>int</strong> <var>lock_id</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>lock_set</var> +<dd> +[in send right] The port naming the lock set which represents the +lock. +<p> +<dt> <var>lock_id</var> +<dd> +[in scalar] The lock, represented by the lock set, to be released. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>lock_release</strong> function release the ownership of the specified lock. +If the calling thread does not own the lock then the call will fail. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The specified lock_set is invalid, or the lock_id is out of range. + <p> + <dt> <strong>KERN_INVALID_RIGHT</strong> + <dd> + The specified task does not own the specified lock. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The ownership of the lock was released. +<p> +<dt> <strong>KERN_LOCK_SET_DESTROYED</strong> +<dd> +The specified lock has been destroyed. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="lock_acquire.html"><strong>lock_acquire</strong></a>, +<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, +<a href="lock_try.html"><strong>lock_try</strong></a>, +<a href="lock_handoff.html"><strong>lock_handoff</strong></a>, +<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, +<a href="lock_set_create.html"><strong>lock_set_create</strong></a>, +<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. diff --git a/osfmk/man/lock_set_create.html b/osfmk/man/lock_set_create.html index f87df20ee..8ca303599 100755 --- a/osfmk/man/lock_set_create.html +++ b/osfmk/man/lock_set_create.html @@ -1 +1,73 @@ -<h2>lock_set_create</h2> <hr> <p> <strong>Function</strong> - Create a new lock set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t lock_set_create</strong> <strong>(task_t</strong> <var>task</var>, <strong>lock_set_t</strong> <var>lock_set</var>, <strong>int</strong> <var>locks</var>, <strong>int</strong> <var>policy</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> The task receiving the send right to the newly created lock set. <p> <dt> <var>lock_set</var> <dd> [out send right] The port naming the lock set which represents the lock. <p> <dt> <var>locks</var> <dd> [in scalar] The number of locks the lock set will represent (must be a positive value). <p> <dt> <var>policy</var> <dd> [in scalar] The blocked thread wakeup policy for the newly created lock set. Valid policies are: <dl> <p> <dt> SYNC_POLICY_FIFO <dd> a first-in-first-out policy for scheduling thread wakeup. <p> <dt> SYNC_POLICY_FIXED_PRIORITY <dd> a fixed priority policy for scheduling thread wakeup. </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>lock_set_create</strong> function creates a new lock set representing a collection of associated locks. The lock set is associated with the specified task. A send right naming the lock set is returned to the caller. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The lock set was created. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> Either the task or policy argument is invalid, or the locks argument has a value that is less than or equal to zero. <p> <dt> <strong>KERN_RESOURCE_SHORTAGE</strong> <dd> The kernel could not allocate the lock set. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="lock_acquire.html"><strong>lock_acquire</strong></a>, <a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, <a href="lock_try.html"><strong>lock_try</strong></a>, <a href="lock_handoff.html"><strong>lock_handoff</strong></a>, <a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, <a href="lock_try.html"><strong>lock_try</strong></a>, <a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. \ No newline at end of file +<h2>lock_set_create</h2> +<hr> +<p> +<strong>Function</strong> - Create a new lock set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t lock_set_create</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>lock_set_t</strong> <var>lock_set</var>, + <strong>int</strong> <var>locks</var>, + <strong>int</strong> <var>policy</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +The task receiving the send right to the newly created lock set. +<p> +<dt> <var>lock_set</var> +<dd> +[out send right] The port naming the lock set which represents the lock. +<p> +<dt> <var>locks</var> +<dd> +[in scalar] The number of locks the lock set will represent (must be a positive value). +<p> +<dt> <var>policy</var> +<dd> +[in scalar] The blocked thread wakeup policy for the newly created lock set. Valid policies are: + <dl> +<p> +<dt> SYNC_POLICY_FIFO +<dd> +a first-in-first-out policy for scheduling thread wakeup. +<p> +<dt> SYNC_POLICY_FIXED_PRIORITY +<dd> +a fixed priority policy for scheduling thread wakeup. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>lock_set_create</strong> function creates a new lock set representing a +collection of associated locks. The lock set is associated with the +specified task. A send right naming the lock set is returned to the +caller. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The lock set was created. +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +Either the task or policy argument is invalid, or the locks argument +has a value that is less than or equal to zero. +<p> +<dt> <strong>KERN_RESOURCE_SHORTAGE</strong> +<dd> +The kernel could not allocate the lock set. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="lock_acquire.html"><strong>lock_acquire</strong></a>, +<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, +<a href="lock_try.html"><strong>lock_try</strong></a>, +<a href="lock_handoff.html"><strong>lock_handoff</strong></a>, +<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, +<a href="lock_try.html"><strong>lock_try</strong></a>, +<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. diff --git a/osfmk/man/lock_set_destroy.html b/osfmk/man/lock_set_destroy.html index aa81470ea..f32c80686 100755 --- a/osfmk/man/lock_set_destroy.html +++ b/osfmk/man/lock_set_destroy.html @@ -1 +1,58 @@ -<h2>lock_set_destroy</h2> <hr> <p> <strong>Function</strong> - Destroy a lock set and its associated locks. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t lock_set_destroy</strong> <strong>(task_t</strong> <var>task</var>, <strong>lock_set_t</strong> <var>lock_set</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> The task associated with the lock set. <p> <dt> <var>lock_set</var> <dd> [in send right] The port naming the lock set being destroyed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>lock_set_destroy</strong> function will destroy a lock set and all of its associated locks. Threads that are blocked on locks represented by the destroyed lock set are unblocked and will receive a KERN_LOCK_SET_DESTROYED error message indicating that the lock set was destroyed. The <strong>lock_set_destroy</strong> function will only succeed if the specified task is associated with the specified lock set. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified lock set or task is invalid. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> The specified task does not own the specified lock set. <p> <dt> <strong>KERN_LOCK_SET_DESTROYED</strong> <dd> The specified lock set does not exist. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The lock set was destroyed. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="lock_acquire.html"><strong>lock_acquire</strong></a>, <a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, <a href="lock_try.html"><strong>lock_try</strong></a>, <a href="lock_handoff.html"><strong>lock_handoff</strong></a>, <a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, <a href="lock_try.html"><strong>lock_try</strong></a>, <a href="lock_set_create.html"><strong>lock_set_create</strong></a>. \ No newline at end of file +<h2>lock_set_destroy</h2> +<hr> +<p> +<strong>Function</strong> - Destroy a lock set and its associated locks. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t lock_set_destroy</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>lock_set_t</strong> <var>lock_set</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +The task associated with the lock set. +<p> +<dt> <var>lock_set</var> +<dd> +[in send right] The port naming the lock set being destroyed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>lock_set_destroy</strong> function will destroy a lock set and all of its +associated locks. Threads that are blocked on locks represented by the +destroyed lock set are unblocked and will receive a +KERN_LOCK_SET_DESTROYED error message indicating that the lock set was +destroyed. The <strong>lock_set_destroy</strong> function will only succeed if the +specified task is associated with the specified lock set. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The specified lock set or task is invalid. + <p> + <dt> <strong>KERN_INVALID_RIGHT</strong> + <dd> + The specified task does not own the specified lock set. +<p> + <dt> <strong>KERN_LOCK_SET_DESTROYED</strong> + <dd> + The specified lock set does not exist. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The lock set was destroyed. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="lock_acquire.html"><strong>lock_acquire</strong></a>, +<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, +<a href="lock_try.html"><strong>lock_try</strong></a>, +<a href="lock_handoff.html"><strong>lock_handoff</strong></a>, +<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, +<a href="lock_try.html"><strong>lock_try</strong></a>, +<a href="lock_set_create.html"><strong>lock_set_create</strong></a>. diff --git a/osfmk/man/lock_try.html b/osfmk/man/lock_try.html index 2fe0a676b..7517f50ef 100755 --- a/osfmk/man/lock_try.html +++ b/osfmk/man/lock_try.html @@ -1 +1,62 @@ -<h2>lock_try</h2> <hr> <p> <strong>Function</strong> - Attempt to acquire access rights to a lock. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t lock_try</strong> <strong>(lock_set_t</strong> <var>lock_set</var>, <strong>int</strong> <var>lock_id</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>lock_set</var> <dd> [in send right] The port naming the lock set which represents the lock. <p> <dt> <var>lock_id</var> <dd> [in scalar] The lock, represented by the lock set, to be acquired. </dl> <h3>DESCRIPTION</h3> <p> The <strong>lock_try</strong> function attempts to acquire the specified lock without blocking. The return value indicates whether the lock was acquired. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified lock_set is invalid, or the lock_id is out of range. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The lock was acquired. <p> <dt> <strong>KERN_LOCK_UNSTABLE</strong> <dd> The acquired lock has an unstable state. <p> <dt> <strong>KERN_LOCK_SET_DESTROYED</strong> <dd> The specified lock has been destroyed. <p> <dt> <strong>KERN_LOCK_OWNED</strong> <dd> Another thread currently owns the requested lock. <p> <dt> <strong>KERN_LOCK_OWNED_SELF</strong> <dd> The calling thread already owns the lock. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="lock_acquire.html"><strong>lock_acquire</strong></a>, <a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, <a href="lock_release.html"><strong>lock_release</strong></a>, <a href="lock_handoff.html"><strong>lock_handoff</strong></a>, <a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, <a href="lock_set_create.html"><strong>lock_set_create</strong></a>, <a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. \ No newline at end of file +<h2>lock_try</h2> +<hr> +<p> +<strong>Function</strong> - Attempt to acquire access rights to a lock. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t lock_try</strong> + <strong>(lock_set_t</strong> <var>lock_set</var>, + <strong>int</strong> <var>lock_id</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>lock_set</var> +<dd> +[in send right] The port naming the lock set which represents the lock. +<p> +<dt> <var>lock_id</var> +<dd> +[in scalar] The lock, represented by the lock set, to be acquired. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>lock_try</strong> function attempts to acquire the specified lock without +blocking. The return value indicates whether the lock was acquired. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The specified lock_set is invalid, or the lock_id is out of range. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The lock was acquired. +<p> +<dt> <strong>KERN_LOCK_UNSTABLE</strong> +<dd> +The acquired lock has an unstable state. +<p> +<dt> <strong>KERN_LOCK_SET_DESTROYED</strong> +<dd> +The specified lock has been destroyed. +<p> +<dt> <strong>KERN_LOCK_OWNED</strong> +<dd> +Another thread currently owns the requested lock. +<p> +<dt> <strong>KERN_LOCK_OWNED_SELF</strong> +<dd> +The calling thread already owns the lock. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="lock_acquire.html"><strong>lock_acquire</strong></a>, +<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>, +<a href="lock_release.html"><strong>lock_release</strong></a>, +<a href="lock_handoff.html"><strong>lock_handoff</strong></a>, +<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>, +<a href="lock_set_create.html"><strong>lock_set_create</strong></a>, +<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>. diff --git a/osfmk/man/mach_host_self.html b/osfmk/man/mach_host_self.html index 7294f4794..d1f884bd2 100755 --- a/osfmk/man/mach_host_self.html +++ b/osfmk/man/mach_host_self.html @@ -1 +1,28 @@ -<h2>mach_host_self</h2> <hr> <p> <strong>System Trap</strong> - Returns the host self port <h3>SYNOPSIS</h3> <pre> host_name_port_t mach_host_self( void );</strong> </pre> <h3>PARAMETERS</h3> <p> None. <h3>DESCRIPTION</h3> <p> The <strong>mach_host_self</strong> function returns send rights to the task's host self port. By default, this is the name port for the current host but can be a different value if so set. <h3>RETURN VALUES</h3> <p> [host-self send right] Send rights to the host's name port. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_info.html"><strong>host_info</strong></a>, <a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>. \ No newline at end of file +<h2>mach_host_self</h2> +<hr> +<p> +<strong>System Trap</strong> - Returns the host self port +<h3>SYNOPSIS</h3> +<pre> +host_name_port_t mach_host_self( void );</strong> +</pre> +<h3>PARAMETERS</h3> +<p> +None. + +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_host_self</strong> function +returns send rights to the task's host self port. +By default, this is the name port for the current host +but can be a different value if so set. + +<h3>RETURN VALUES</h3> +<p> +[host-self send right] Send rights to the host's name port. + +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_info.html"><strong>host_info</strong></a>, +<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>. diff --git a/osfmk/man/mach_msg.html b/osfmk/man/mach_msg.html index bf700cd34..50c7de0b7 100755 --- a/osfmk/man/mach_msg.html +++ b/osfmk/man/mach_msg.html @@ -1 +1,987 @@ -<h2>mach_msg</h2> <hr> <p> <strong>System Trap</strong> / <strong>Function</strong> - Send and/or receive a message from the target port. <h3>SYNOPSIS</h3> <pre> <strong>mach_msg_return_t mach_msg</strong> <strong>(mach_msg_header_t</strong> <var>msg</var>, <strong>mach_msg_option_t</strong> <var>option</var>, <strong>mach_msg_size_t</strong> <var>send_size</var>, <strong>mach_msg_size_t</strong> <var>receive_limit</var>, <strong>mach_port_t</strong> <var>receive_name</var>, <strong>mach_msg_timeout_t</strong> <var>timeout</var>, <strong>mach_port_t</strong> <var>notify</var><strong>);</strong> <strong>mach_msg_return_t mach_msg_overwrite</strong> <strong>(mach_msg_header_t*</strong> <var>send_msg</var>, <strong>mach_msg_option_t</strong> <var>option</var>, <strong>mach_msg_size_t</strong> <var>send_size</var>, <strong>mach_msg_size_t</strong> <var>receive_limit</var>, <strong>mach_port_t</strong> <var>receive_name</var>, <strong>mach_msg_timeout_t</strong> <var>timeout</var>, <strong>mach_port_t</strong> <var>notify</var>, <strong>mach_msg_header_t</strong> <var>*receive_msg</var>, <strong>mach_msg_size_t</strong> <var>receive_msg_size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>msg</var> <dd> [pointer to in/out structure containing random and reply rights] A message buffer used by <strong>mach_msg</strong> both for send and receive. This must be naturally aligned. <p> <dt> <var>send_msg</var> <dd> [pointer to in structure containing random and reply rights] The mes- sage buffer to be sent. This must be naturally aligned. <p> <dt> <var>option</var> <dd> [in scalar] Message options are bit values, combined with bitwise-or. One or both of MACH_SEND_MSG and MACH_RCV_MSG should be used. Other options act as modifiers. <p> <dt> <var>send_size</var> <dd> [in scalar] When sending a message, specifies the size of the message buffer to be sent (the size of the header and body) in bytes. Otherwise zero should be supplied. <p> <dt> <var>receive_limit</var> <dd> [in scalar] When receiving a message, specifies the maximum size of the msg or receive_msg buffer in bytes. Otherwise zero should be sup- plied. <p> <dt> <var>receive_name</var> <dd> [in random right] When receiving a message, specifies the port or port set. Otherwise MACH_PORT_NULL should be supplied. <p> <dt> <var>timeout</var> <dd> [in scalar] When using the MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT options, specifies the time in milliseconds to wait before giving up. Otherwise MACH_MSG_TIMEOUT_NONE should be supplied. <p> <dt> <var>notify</var> <dd> [in notify receive right] When using the MACH_SEND_CANCEL and MACH_RCV_NOTIFY options, specifies the port used for the notification. Otherwise MACH_PORT_NULL should be supplied. <p> <dt> <var>receive_msg</var> <dd> [pointer to in/out structure] A message buffer into which a message (header and body) will be received. This must be naturally aligned. By default (<strong>mach_msg</strong>), any received message will overwrite the send message buffer. This buffer is in/out only if the MACH_RCV_OVERWRITE option is used; otherwise this buffer is out only. <p> <dt> <var>receive_msg_size</var> <dd> [in scalar] When using the MACH_RCV_OVERWRITE option, specifies the size (in bytes) of the receive "message" that is to be used by <strong>mach_msg</strong> to indicate the disposition of received out-of-line regions. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_msg</strong> system call sends and receives Mach messages. Mach messages contain data, which can include port rights and addresses of large regions of memory. <strong>mach_msg</strong> uses the same buffer for sending and receiving a message; the other calls permit separate send and receive buffers (although they may be specified to be the same). If the option argument contains MACH_SEND_MSG, the call sends a message. The <var>send_size</var> argument specifies the size of the message buffer (header and body) to send. The msgh_remote_port field of the message header specifies the destination of the message. If the option argument contains MACH_RCV_MSG, it receives a message. The receive_limit argument specifies the size of a buffer that will receive the message; messages that are larger are not received. The receive_name argument specifies the port or port set from which to receive. <p> If the option argument contains both MACH_SEND_MSG and MACH_RCV_MSG, then <strong>mach_msg</strong> does both send and receive operations (in that order). If the send operation encounters an error (any return code other than MACH_MSG_SUCCESS), the call returns immediately without attempting the receive operation. Semantically the combined call is equivalent to separate send and receive calls, but it saves a system call and enables other internal optimizations. If the option argument specifies neither MACH_SEND_MSG nor MACH_RCV_MSG, <strong>mach_msg</strong> does nothing. Some options, like MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT, share a supporting argument. If these options are used together, they make independent use of the supporting argument's value. <h3>NOTES</h3> <p> The Mach kernel provides message-oriented, capability-based inter-process communication. The inter-process communication (IPC) primitives efficiently support many different styles of interaction, including remote procedure calls, object-oriented distributed programming, streaming of data, and sending very large amounts of data. <h4>Major Concepts</h4> <p> The IPC primitives operate on three abstractions: messages, ports, and port sets. User tasks access all other kernel services and abstractions via the IPC primitives. <p> The message primitives let tasks send and receive messages. Tasks send messages to ports. Messages sent to a port are delivered reliably (messages may not be lost) and are received in the order in which they were sent via send rights by a given sending task (or a given kernel). (Messages sent to send-once rights are unordered.) <p> Messages contain a fixed-size header and a variable-sized message body containing kernel and user data, and a variable-size trailer of kernel appended message attributes. The header describes the destination and the size of the message (header plus body). The message body contains descriptions of additional port rights to be transmitted, descriptions of "out-of-line" memory regions to be sent and a variable amount of user data, which typically includes type conversion information. The out-of-line memory regions (including out-of-line port arrays) are (typically) disjoint from the message body. The IPC implementation makes use of the VM system to efficiently transfer large amounts of data. The message can contain the addresses of regions of the sender's address space which should be transferred as part of the message. <p> When a task receives a message containing such out-of-line regions of data, the data can appear in unused portions or overwrite an existing portion of the receiver's address space (depending on the requested receive options). Under favorable circumstances, the transmission of out-of-line data is optimized so that sender and receiver share the physical pages of data copy-on-write, and no actual data copy occurs unless the pages are written. Regions of memory up to 4 gigabytes may be sent in this manner. <p> Ports hold a queue of messages. Tasks operate on a port to send and receive messages by exercising capabilities (rights) for the port. Multiple tasks can hold send rights for a port. Tasks can also hold send-once rights, which grant the ability to send a single message. Only one task can hold the receive capability (receive right) for a port. <p> Port rights can be transferred between tasks via messages. The sender of a message can specify in the message that the message contains a port right. If a message contains a receive right for a port, the receive right is removed from the sender of the message and transferred to the receiver of the message. While the receive right is in transit, tasks holding send rights can still send messages to the port, and they are queued until a task acquires the receive right and uses it to receive the messages. <p> Tasks can receive messages from ports and port sets. The port set abstraction allows a single thread to wait for a message from any of several ports. Tasks manipulate port sets with a port set name, which is taken from the same name space as are the port rights. The port-set name may not be transferred in a message. A port set holds receive rights, and a receive operation on a port set blocks waiting for a message sent to any of the constituent ports. A port may not be- long to more than one port set, and if a port is a member of a port set, the holder of the receive right can't receive directly from the port. <p> Port rights are a secure, location-independent way of naming ports. The port queue is a protected data structure, only accessible via the kernel's exported message primitives. Rights are also protected by the kernel; there is no way for a malicious user task to guess a port's internal name and send a message to a port to which it shouldn't have access. Port rights do not carry any location in- formation. When a receive right for a port moves from task to task, and even between tasks on different machines, the send rights for the port remain unchanged and continue to function. <h4>Port Rights</h4> <p> Each task has its own space of port rights. Port rights are named with positive (unsigned) integers. For all architectures, sizeof (mach_port_t) = sizeof (mach_port_name_t) = sizeof (void*) and so user space addresses may be used as port names, except for the reserved values MACH_PORT_NULL (0) and MACH_PORT_DEAD (all 1 bits). When the kernel chooses a name for a new right, however, it is free to pick any unused name (one which denotes no right) in the space. <p> There are three basic kinds of rights: receive rights, send rights and send-once rights. A port name can name any of these types of rights, or name a port-set, be a dead name, or name nothing. Dead names are not capabilities. They act as place-holders to prevent a name from being otherwise used. <p> A port is destroyed, or dies, when its receive right is de-allocated. When a port dies, send and send-once rights for the port turn into dead names. Any messages queued at the port are destroyed, which de-allocates the port rights and out-of-line memory in the messages. <p> Each send-once right held by a task has a different name. In contrast, when a task holds send rights or a receive right for a port, the rights share a single name. <p> Tasks may hold multiple user-references for send rights. When a task receives a send right which it already holds, the kernel increments the right's user-reference count. When a task de-allocates a send right, the kernel decrements its user-reference count, and the task only loses the send right when the count goes to zero. <p> Send-once rights always have a user reference count of one. Tasks may hold multiple user references for dead names. Each send-once right generated guarantees the receipt of a single message, either a message sent to that send-once right or, if the send-once right is in any way destroyed, a send-once notification. <p> A message can carry port rights; the msgh_remote or msgh_local fields in the message header or the disposition field in a message body descriptor specify the type of port right and how the port right is to be extracted from the caller. The values MACH_PORT_NULL and MACH_PORT_DEAD are valid in place of a port right in a message body. <p> In a sent message, the following mach_msg_type_name_t values denote port rights: <dl> <dt> MACH_MSG_TYPE_MAKE_SEND <dd> The message will carry a send right, but the caller must supply a receive right. The send right is created from the receive right, and the receive right's make-send count is incremented. <dt> MACH_MSG_TYPE_COPY_SEND <dd> The message will carry a send right, and the caller must supply a send right. The user reference count for the supplied send right is not changed. The caller may also supply a dead name and the receiving task will get MACH_PORT_DEAD. <dt> MACH_MSG_TYPE_MOVE_SEND <dd> The message will carry a send right, and the caller must supply a send right. The user reference count for the supplied send right is decremented, and the right is destroyed if the count becomes zero. Unless a receive right remains, the name becomes available for recycling. The caller may also supply a dead name, which loses a user reference, and the receiving task will get MACH_PORT_DEAD. <dt> MACH_MSG_TYPE_MAKE_SEND_ONCE <dd> The message will carry a send-once right, but the caller must supply a receive right. The send-once right is created from the receive right. Note that send once rights can only be created from the receive right. <dt> MACH_MSG_TYPE_MOVE_SEND_ONCE <dd> The message will carry a send-once right, and the caller must supply a send-once right. The caller loses the supplied send-once right. The caller may also supply a dead name, which loses a user reference, and the receiving task will get MACH_PORT_DEAD. <dt> MACH_MSG_TYPE_MOVE_RECEIVE <dd> The message will carry a receive right, and the caller must supply a receive right. The caller loses the supplied receive right, but retains any send rights with the same name. The make-send count and sequence number of the receive right are reset to zero and no-more-senders notification requests are cancelled (with a send-once notification being sent to the no-more-senders notification right), but the port retains other attributes like queued messages and extant send and send-once rights. If a message carries a send or send-once right, and the port dies while the message is in transit, then the receiving task will get MACH_PORT_DEAD instead of a right. </dl> <p> The following mach_msg_type_name_t values in a received message indicate that it carries port rights: <dl> <dt> MACH_MSG_TYPE_PORT_SEND <dd> This value is an alias for MACH_MSG_TYPE_MOVE_SEND. The message carried a send right. If the receiving task already has send and/ or receive rights for the port, then that name for the port will be reused. Otherwise, the right will have a new, previously unused, name. If the task already has send rights, it gains a user reference for the right (un- less this would cause the user-reference count to overflow). Otherwise, it acquires send rights, with a user-reference count of one. <dt> MACH_MSG_TYPE_PORT_SEND_ONCE <dd> This value is an alias for MACH_MSG_TYPE_MOVE_SEND_ONCE. The message carried a send-once right. The right will have a new, previously unused, name. <dt> MACH_MSG_TYPE_PORT_RECEIVE <dd> This value is an alias for MACH_MSG_TYPE_MOVE_RECEIVE. The message carried a receive right. If the receiving task already has send rights for the port, then that name for the port will be reused; otherwise, the right will have a new, previously unused name. </dl> <p> It is also possible to send a (nearly unbounded) array of port rights "out-of-line". All of the rights named by the array must be of the same type. The array is physically copied with the message body proper. The array of port right (names) can be received by the receiver using the same options available for out-of-line data reception described below. <h4>Memory</h4> <p> A message can contain one or more regions of the sender's address space which are to be transferred as part of the message. The message carries a logical copy of the memory. For this "out-of-line" memory, the kernel can copy the data or use virtual memory techniques to defer any actual page copies unless the sender or the receiver modifies the data, the physical pages remain shared. <p> The sender of the message must explicitly request an out-of-line transfer. Such a region is described as an arbitrary region of the sender's address space. The sender always sees this memory as being copied to the receiver. <p> For each region, the sender has a de-allocate option. If the option is set and the out-of-line memory region is not null, then the region is implicitly de-allocated from the sender, as if by vm_deallocate. In particular, the start address is truncated down and the end address rounded up so that every page overlapped by the memory region is de-allocated (thereby possibly de-allocating more memory than is effectively transmitted). The use of this option effectively changes the memory copy to a memory movement. Aside from possibly optimizing the sender's use of memory, the de-allocation option allows the kernel to more efficiently handle the transfer of memory. <p> For each region, the sender has the choice of permitting the kernel to choose a transmission strategy or the choice of requiring physical copy: <dl> <dt> MACH_MSG_VIRTUAL_COPY <dd> In a sent message, this flag allows the kernel to choose any mechanism to transmit the data. For large regions, this involves constructing a virtual copy of the pages containing the region. The portion of the first page preceding the data and the portion of the last page following the data are not copied (and will appear as zero if the virtual copy is dynamically allocated in the receiver). <p> In a received message, this flag indicates that the kernel transmitted a virtual copy. Access to the received memory may involve interactions with the memory manager managing the sender's original data. Integri- ty-conscious receivers should exercise caution when dealing with out- of-line memory from un-trustworthy sources. Receivers concerned about deterministic access time should also exercise caution. The dynamic allocation option guarantees that the virtual copy will not be di- rectly referenced during the act of receiving the message. <dt> MACH_MSG_PHYSICAL_COPY <dd> In a sent message, this flag requires that the kernel construct an actual copy of the memory (either into wired kernel memory or default memory managed space). There is a (fairly large) limit on the amount of data that can be physically copied in a message. Port arrays always assume this option when sent. <p> In a received message, this flag indicates that the kernel did transmit a physical copy. </dl> <p> The receiver has two options for the reception of out-of-line memory (or "out-of-line" port arrays): allocation and overwrite. In the absence of the MACH_RCV_OVERWRITE option, all out-of-line re- gions are dynamically allocated. Allocated out-of-line memory arrives somewhere in the receiver's address space as new memory. It has the same inheritance and protection attributes as newly vm_allocate'ed memory. The receiver has the responsibility of de-allocating (with vm_deallocate) the memory when it is no longer needed. If the message contains more than one region, each will be allocated its own region, not necessarily contiguously. If the sender's data was transmitted as a virtual copy the allocated region will have the same data alignment within the page; otherwise, the received data will appear starting at the beginning of a page. <p> If the MACH_RCV_OVERWRITE option is set, the receiver can specify how each received region is to be processed (dynamically allocated as described above, or written over existing memory). With this option, the contents of the receive buffer (receive_msg) are examined by the kernel. The kernel scans the descriptors in the receive buffer "message" to determine how to handle each out-of-line region. (Note: whereas receive_limit is the maximum size of the receive buffer, receive_msg_size is the amount filled in with this "message".) The kernel uses each out-of-line data descriptor (in order) to specify the processing for each received data region in turn, each out-of-line port array descriptor is used correspondingly. (Intermingled port descriptors are ignored when matching descriptors between the incoming message and the receive buffer list.) <p> The copy option in the matching descriptor specifies the processing: <dl> <dt> MACH_MSG_OVERWRITE <dd> This flag indicates that the region should write over a specified region of the receiver's address space, as indicated by the address and size/ count fields of the descriptor. The full range overwritten must already exist (be allocated or mapped) in the receiver's address space. Depending on the nature of the data transmission this overwrite may involve virtual memory manipulations or it may involve actual data copy. <dt> MACH_MSG_ALLOCATE <dd> This flag indicates that the region is to be dynamically allocated. No other descriptor values are relevant. </dl> <p> If not enough descriptors appear in the receive buffer to describe all received regions, additional regions are dynamically allocated. If the receiver specifies more descriptors than there are regions in the received message, the additional descriptors are ignored (and do not appear in the final received message). <p> Note that the receive buffer descriptors will be overwritten: The size fields in descriptors will be updated (when scanned, they specified the maximum sizes of regions, when received, they specify the actual sizes of received regions). The copy fields in descriptors will be updated (when scanned, they specified allocate versus overwrite, when received, they indicate whether the region was physically or virtually copied). The descriptors may appear in different positions (given intermingled port descriptors). Descriptors that were not used (because there were not that many received regions) will be discarded. <p> Null out-of-line memory is legal. If the out-of-line region size is zero, then the region's specified address is ignored. A receive allocated null out-of-line memory region always has a zero address. Unaligned addresses and region sizes that are not page multiples are legal. A received message can also contain regions with unaligned addresses and sizes which are not multiples of the page size. <h4>Message Send</h4> <p> The send operation queues a message to a port. The message carries a copy of the caller's data. After the send, the caller can freely modify the message buffer or the out-of-line memory regions and the message contents will remain unchanged. <p> The message carries with it the security ID of the sender, which the receiver can request in the message trailer. <p> Message delivery is reliable and sequenced. Reception of a message guarantees that all messages previously sent to the port by a single task (or a single kernel) via send rights have been received and that they are received in the order in which they were sent. Messages sent to send-once rights are unordered. <p> If the destination port's queue is full, several things can happen. If the message is sent to a send-once right (msgh_remote_port carries a send-once right), then the kernel ignores the queue limit and delivers the message. Otherwise the caller blocks until there is room in the queue, unless the MACH_SEND_TIMEOUT option is used. If a port has several blocked senders, then any of them may queue the next message when space in the queue becomes available, with the proviso that a blocked sender will not be indefinitely starved. These options modify MACH_SEND_MSG. If MACH_SEND_MSG is not also specified, they are ignored. <dl> <dt> MACH_SEND_TIMEOUT <dd> The timeout argument should specify a maximum time (in milliseconds) for the call to block before giving up. If the message can't be queued before the timeout interval elapses, then the call returns MACH_SEND_TIMED_OUT. A zero timeout is legitimate. <dt> MACH_SEND_INTERRUPT <dd> If specified, the <strong>mach_msg</strong> call will return MACH_SEND_INTERRUPTED if a software interrupt aborts the call. Otherwise, the send operation will be retried. <dt> MACH_SEND_TRAILER <dd> If set, the kernel, instead of determining the message attributes itself, will accept a formatted message trailer from the sender. The supplied trailer must be of the latest version supported by the kernel, and must contain all message attributes defined by the kernel. Only tasks with a security ID of KERNEL_SECURITY_ID can use this option; the intended use of this option is in support of the Net Message server. The trailer must follow the message in memory as it would appear in a received message. (The send_size argument to <strong>mach_msg</strong> still indicates the size of the message proper, not including this trailer.) </dl> <p> The queueing of a message carrying receive rights may create a circular loop of receive rights and messages, which can never be received. For example, a message carrying a receive right can be sent to that receive right. This situation is not an error, but the kernel will garbage-collect such loops, destroying the messages. Some return codes, like MACH_SEND_TIMED_OUT, imply that the message was almost sent, but could not be queued. In these situations, the kernel tries to return the message contents to the caller with a pseudo-receive operation. This prevents the loss of port rights or memory which only exist in the message, for example, a receive right which was moved into the message, or out-of-line memory sent with the de-allocate option. <p> The intent of the pseudo-receive operation is to restore, as best as possible, the state prior to attempting the send. This involves restoring the port rights and out-of-line memory regions contained in the message. The port right names and out-of-line addresses in the message send buffer are updated to reflect the new values resulting from their effective reception. The pseudo-receive handles the des- tination and reply rights as any other rights; they are not reversed as is the appearance in a normal received message. Also, no trailer is appended to the message. After the pseudo-receive, the message is ready to be resent. If the message is not resent, note that out-of-line memory regions may have moved and some port rights may have changed names. <p> Although unlikely, the pseudo-receive operation may encounter resource shortages. This is similar to a MACH_RCV_BODY_ERROR return code from a receive operation. When this happens, the normal send return codes are augmented with the MACH_MSG_IPC_SPACE, MACH_MSG_VM_SPACE, MACH_MSG_IPC_KERNEL and MACH_MSG_VM_KERNEL bits to indicate the nature of the resource shortage. <h4>Message Receive</h4> <p> The receive operation de-queues a message from a port. The receiving task acquires the port rights and out-of-line memory regions carried in the message. The receive_name argument specifies a port or port set from which to receive. If a port is specified, the caller must possess the receive right for the port and the port must not be a member of a port set. If no message is present, the call blocks, subject to the MACH_RCV_TIMEOUT option. <p> If a port set is specified, the call will receive a message sent to any of the member ports. It is permissible for the port set to have no member ports, and ports may be added and removed while a receive from the port set is in progress. The received message can come from any of the member ports which have messages, with the proviso that a member port with messages will not be indefinitely starved. The msgh_local_port field in the received message header specifies from which port in the port set the message came. <p> The receive_limit argument specifies the size of the caller's message buffer (which must be big enough for the message header, body and trailer); the msgh_size field of the received message indicates the actual size of the received message header and body. The <strong>mach_msg</strong> call will not receive a message larger than receive_limit. Messages that are too large are destroyed, unless the MACH_RCV_LARGE option is used. Following the received data, at the next natural boundary, is a message trailer. The msgh_size field of the received message does not include the length of this trailer; the trailer's length is given by the msgh_trailer_size field within the trailer. The receiver of a message is given a choice as to what trailer format is desired, and, within that format, which of the leading trailer attributes are desired (that is, to get trailer element three, the receiver must also accept elements one and two). For any given trailer format (of which there is currently only one), the trailer is compatibly extended by adding additional elements to the end. <p> Received messages are stamped (in the trailer) with a sequence number, taken from the port from which the message was received. (Messages received from a port set are stamped with a sequence number from the appropriate member port.) Newly created ports start with a zero sequence number, and the sequence number is reset to zero whenever the port's receive right moves between tasks. When a message is de-queued from the port, it is stamped with the port's sequence number and the port's sequence number is then incremented. (Note that this occurs whether or not the receiver requests the sequence number in the trail- er.) The de-queue and increment operations are atomic, so that multiple threads receiving messages from a port can use the msgh_seqno field to reconstruct the original order of the messages. <p> The destination and reply ports are reversed in a received message header. The msgh_local_port field carries the name of the destination port, from which the message was received, and the msgh_remote_port field carries the reply port right. The bits in msgh_bits are also reversed. The MACH_MSGH_BITS_LOCAL bits have a value of MACH_MSG_TYPE_PORT_SEND_ONCE or MACH_MSG_TYPE_PORT_SEND depending on the type of right to which the message was sent. The MACH_MSGH_BITS_REMOTE bits describe the reply port right. <p> A received message can contain port rights and out-of-line memory. The msgh_local_port field does not carry a port right; the act of receiving the message consumes the send or send-once right for the destination port. The msgh_remote_port field does carry a port right, and the message can carry additional port rights and memory if the MACH_MSGH_BITS_COMPLEX bit is set. Received port rights and memory should be consumed or de-allocated in some fashion. In almost all cases, msgh_local_port will specify the name of a receive right, either receive_name, or, if receive_name is a port set, a member of receive_name. <p> If other threads are concurrently manipulating the receive right, the situation is more complicated. If the receive right is renamed during the call, then msgh_local_port specifies the right's new name. If the caller loses the receive right after the message was de-queued from it, then <strong>mach_msg</strong> will proceed instead of returning MACH_RCV_PORT_DIED. If the receive right was destroyed, then msgh_local_port specifies MACH_PORT_DEAD. If the receive right still exists, but isn't held by the caller, then msgh_local_port specifies MACH_PORT_NULL. <p> The following options modify MACH_RCV_MSG. If MACH_RCV_MSG is not also specified, they are ignored. <dl> <dt> MACH_RCV_TIMEOUT <dd> The timeout argument should specify a maximum time (in milliseconds) for the call to block before giving up. If no message arrives before the timeout interval elapses, then the call returns MACH_RCV_TIMED_OUT. A zero timeout is legitimate. <dt> MACH_RCV_NOTIFY <dd> The notify argument should specify a receive right for a notify port. If receiving the reply port creates a new port right in the caller, then the notify port is used to request a dead-name notification for the new port right. <dt> MACH_RCV_INTERRUPT <dd> If specified, the <strong>mach_msg</strong> call will return MACH_RCV_INTERRUPTED if a software interrupt aborts the call. Otherwise, the receive operation will be retried. <dt> MACH_RCV_OVERWRITE <dd> If specified, the message buffer specified by receive_msg (or msg), of length receive_msg_size, will be scanned for out-of-line descriptors to specify the processing to be done when receiving out-of-line regions. This option is only allowed for <strong>mach_msg_overwrite</strong>. <dt> MACH_RCV_LARGE <dd> If the message is larger than receive_limit or an out-of-line region is larger than the size allowed by a corresponding receive descriptor (MACH_RCV_OVERWRITE), the message remains queued instead of being destroyed. If the header, trailer and body would not fit into receive_limit, only the message header (mach_msg_header) and trailer header (mach_msg_trailer) are returned with the actual size of the message returned in the msgh_size field, the actual size of the trailer returned in the msgh_trailer_size field and an error return value of MACH_RCV_TOO_LARGE. If receive_limit is sufficient but an out-of-line descriptor is not, the message header, trailer and body are received, with out-of-line descriptors set to indicate the nature and size of the out-of-line regions, with an error return of MACH_RCV_SCATTER_SMALL. No out-of-line regions or port rights (including the reply right) will be received. If this option is not specified, messages too large will be de-queued and then destroyed; the caller receives the message header, with all fields correct, including the destination port but excepting the reply port, which is MACH_PORT_NULL and an empty (no additional element) message trailer. <dt> MACH_RCV_TRAILER_TYPE(value) <dd> This macro encodes the type of trailer the kernel must return with the message. If the kernel does not recognize this type, it returns MACH_RCV_INVALID_TRAILER. Currently, only MACH_MSG_TRAILER_FORMAT_0 is supported. <dt> MACH_RCV_TRAILER_ELEMENTS(value) <dd> This macro encodes the number of trailer elements desired. If the ker- nel does not support this number for the requested trailer type, the kernel returns MACH_RCV_INVALID_TRAILER. Zero is a legal value. </dl> <p> The following trailer elements are supported: <dl> <dt> MACH_RCV_TRAILER_SEQNO <dd> Returns the sequence number of the message relative to its port. This value is of type mach_port_seqno_t. <dt> MACH_RCV_TRAILER_SENDER <dd> Returns the security ID of the task that sent the message. This value is of type security_id_t. </dl> <p> If a resource shortage prevents the reception of a port right, the port right is destroyed and the caller sees the name MACH_PORT_NULL. If a resource shortage prevents the reception of an out-of-line memory region, the region is destroyed and the caller sees a zero address. In addition, the corresponding element in the size array is set to zero. A task never receives port rights or memory for which it is not told. <p> The MACH_RCV_HEADER_ERROR return code indicates a resource shortage in the reception of the message header. The reply port and all port rights and memory in the message are destroyed. The caller receives the message header with all fields correct except for the reply port. <p> The MACH_RCV_BODY_ERROR return code indicates a resource shortage in the reception of the message body. The message header, including the reply port, is correct. The kernel attempts to transfer all port rights and memory regions in the body, and only destroys those that can't be transferred. <h4>Atomicity</h4> <p> The <strong>mach_msg</strong> call handles port rights in the message header atomically. Out-of-line memory and port rights in the message body do not enjoy this atomicity guarantee. These elements may be processed front-to-back, back-to-front, in some random order, or even atomically. <p> For example, consider sending a message with the destination port specified as MACH_MSG_TYPE_MOVE_SEND and the reply port specified as MACH_MSG_TYPE_COPY_SEND. The same send right, with one user-refer- ence, is supplied for both the msgh_remote_port and msgh_local_port fields. Because <strong>mach_msg</strong> processes the port rights atomically, this succeeds. If msgh_remote_port were processed before msgh_local_port, then <strong>mach_msg</strong> would return MACH_SEND_INVALID_REPLY in this situation. <p> On the other hand, suppose the destination and reply port are both specified as MACH_MSG_TYPE_MOVE_SEND, and again the same send right with one user-reference is supplied for both. Now the send operation fails, but because it processes the rights atomically, <strong>mach_msg</strong> can return either MACH_SEND_INVALID_DEST or MACH_SEND_INVALID_REPLY. <p> For example, consider receiving a message at the same time another thread is deallocating the destination receive right. Suppose the reply port field carries a send right for the destination port. If the de-allocation happens before the dequeuing, the receiver gets MACH_RCV_PORT_DIED. If the de-allocation happens after the receive, the msgh_local_port and the msgh_remote_port fields both specify the same right, which becomes a dead name when the receive right is de-allocated. If the de-allocation happens between the de-queue and the receive, the msgh_local_port and msgh_remote_port fields both specify MACH_PORT_DEAD. Because the rights are processed atomically, it is not possible for just one of the two fields to hold MACH_PORT_DEAD. <p> The MACH_RCV_NOTIFY option provides a more likely example. Suppose a message carrying a send-once right reply port is received with MACH_RCV_NOTIFY at the same time the reply port is destroyed. If the reply port is destroyed first, then msgh_remote_port specifies MACH_PORT_DEAD and the kernel does not generate a dead-name notification. If the reply port is destroyed after it is received, then msgh_remote_port specifies a dead name for which the kernel generates a dead-name notification. Either the reply port is dead on arrival or notification is requested. <h4>Implementation</h4> <p> <strong>mach_msg</strong> and <strong>mach_msg_overwrite</strong> are wrappers for a system call. They have the responsibility for repeating the interrupted system call. <h3>CAUTIONS</h3> <p> If MACH_RCV_TIMEOUT is used without MACH_RCV_INTERRUPT, then the timeout duration might not be accurate. When the call is interrupted and automatically retried, the original timeout is used. If interrupts occur frequently enough, the timeout interval might never expire. MACH_SEND_TIMEOUT without MACH_SEND_INTERRUPT suffers from the same problem. <h3>RETURN VALUES</h3> <p> The send operation can generate the following return codes. These return codes imply that the call did nothing: <dl> <p> <dt> MACH_SEND_MSG_TOO_SMALL <dd> The specified send_size was smaller than the minimum size for a message. <p> <dt> MACH_SEND_NO_BUFFER <dd> A resource shortage prevented the kernel from allocating a message buffer. <p> <dt> MACH_SEND_INVALID_DATA <dd> The supplied message buffer was not readable. <p> <dt> MACH_SEND_INVALID_HEADER <dd> The msgh_bits value was invalid. <p> <dt> MACH_SEND_INVALID_DEST <dd> The msgh_remote_port value was invalid. <p> <dt> MACH_SEND_INVALID_NOTIFY <dd> When using MACH_SEND_CANCEL, the notify argument did not denote a valid receive right. <p> <dt> MACH_SEND_INVALID_REPLY <dd> The msgh_local_port value was invalid. <p> <dt> MACH_SEND_INVALID_TRAILER <dd> The trailer to be sent does not correspond to the current kernel format, or the sending task does not have the privilege to supply the message attributes. </dl> <p> These return codes imply that some or all of the message was destroyed: <dl> <p> <dt> MACH_SEND_INVALID_MEMORY <dd> The message body specified out-of-line data that was not readable. <p> <dt> MACH_SEND_INVALID_RIGHT <dd> The message body specified a port right which the caller didn't possess. <p> <dt> MACH_SEND_INVALID_TYPE <dd> A kernel processed descriptor was invalid. <p> <dt> MACH_SEND_MSG_TOO_SMALL <dd> The last data item in the message ran over the end of the message. </dl> <p> These return codes imply that the message was returned to the caller with a pseudo-receive operation: <dl> <p> <dt> MACH_SEND_TIMED_OUT <dd> The timeout interval expired. <p> <dt> MACH_SEND_INTERRUPTED <dd> A software interrupt occurred. </dl> <p> This return code implies that the message was queued: <dl> <p> <dt> MACH_MSG_SUCCESS <dd> The message was queued. </dl> <p> The receive operation can generate the following return codes. These return codes imply that the call did not de-queue a message: <dl> <p> <dt> MACH_RCV_INVALID_NAME <dd> The specified receive_name was invalid. <p> <dt> MACH_RCV_IN_SET <dd> The specified port was a member of a port set. <p> <dt> MACH_RCV_TIMED_OUT <dd> The timeout interval expired. <p> <dt> MACH_RCV_INTERRUPTED <dd> A software interrupt occurred. <p> <dt> MACH_RCV_PORT_DIED <dd> The caller lost the rights specified by receive_name. <p> <dt> MACH_RCV_PORT_CHANGED <dd> receive_name specified a receive right which was moved into a port set during the call. <p> <dt> MACH_RCV_TOO_LARGE <dd> When using MACH_RCV_LARGE, the message was larger than receive_limit. The message is left queued, and its actual size is returned in the message header/message body. <p> <dt> MACH_RCV_SCATTER_SMALL <dd> When using MACH_RCV_LARGE with MACH_RCV_OVERWRITE, one or more scatter list descriptors specified an overwrite region smaller than the corresponding incoming region. The message is left queued, and the proper descriptors are returned in the message header/message body. <p> <dt> MACH_RCV_INVALID_TRAILER <dd> The trailer type desired, or the number of trailer elements desired, is not supported by the kernel. </dl> <p> These return codes imply that a message was de-queued and destroyed: <dl> <p> <dt> MACH_RCV_HEADER_ERROR <dd> A resource shortage prevented the reception of the port rights in the message header. <p> <dt> MACH_RCV_INVALID_NOTIFY <dd> When using MACH_RCV_NOTIFY, the notify argument did not denote a valid receive right. <p> <dt> MACH_RCV_INVALID_DATA <dd> The specified message buffer was not writable. <p> <dt> MACH_RCV_TOO_LARGE <dd> When not using MACH_RCV_LARGE, a message larger than receive_limit was de-queued and destroyed. <p> <dt> MACH_RCV_SCATTER_SMALL <dd> When not using MACH_RCV_LARGE with MACH_RCV_OVERWRITE, one or more scatter list descriptors specified an overwrite region smaller than the corresponding incoming region. The message was de-queued and destroyed. <p> <dt> MACH_RCV_OVERWRITE_ERROR <dd> A region specified by a receive overwrite descriptor (MACH_RCV_OVERWRITE) was not allocated or could not be written. <p> <dt> MACH_RCV_INVALID_TYPE <dd> When using MACH_RCV_OVERWRITE, one or more scatter list descriptors did not have the type matching the corresponding incoming message descriptor or had an invalid copy (disposition) field. <p> <dt> MACH_RCV_LIMITS <dd> The combined size of all out-of-line memory regions or the total num- ber of port rights in the message exceeds the limit set for the port. These return codes imply that a message was received: <p> <dt> MACH_RCV_BODY_ERROR <dd> A resource shortage prevented the reception of a port right or out-of- line memory region in the message body. <p> <dt> MACH_MSG_SUCCESS <dd> A message was received. </dl> <p> Resource shortages can occur after a message is de-queued, while transferring port rights and out-of-line memory regions to the receiving task. The <strong>mach_msg</strong> call returns MACH_RCV_HEADER_ERROR or MACH_RCV_BODY_ERROR in this situation. These return codes always carry extra bits (bitwise-or'ed) that indicate the nature of the resource shortage: <dl> <p> <dt> MACH_MSG_IPC_SPACE <dd> There was no room in the task's IPC name space for another port name. <p> <dt> MACH_MSG_VM_SPACE <dd> There was no room in the task's VM address space for an out-of-line memory region. <p> <dt> MACH_MSG_IPC_KERNEL <dd> A kernel resource shortage prevented the reception of a port right. <p> <dt> MACH_MSG_VM_KERNEL <dd> A kernel resource shortage prevented the reception of an out-of-line memory region. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_allocate.html"><strong>vm_allocate</strong></a>, <a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, <a href="vm_write.html"><strong>vm_write</strong></a>, <a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, <p> Data Structures: mach_msg_header. \ No newline at end of file +<h2>mach_msg</h2> +<hr> +<p> +<strong>System Trap</strong> / <strong>Function</strong> - Send and/or receive a message from the target port. +<h3>SYNOPSIS</h3> +<pre> +<strong>mach_msg_return_t mach_msg</strong> + <strong>(mach_msg_header_t</strong> <var>msg</var>, + <strong>mach_msg_option_t</strong> <var>option</var>, + <strong>mach_msg_size_t</strong> <var>send_size</var>, + <strong>mach_msg_size_t</strong> <var>receive_limit</var>, + <strong>mach_port_t</strong> <var>receive_name</var>, + <strong>mach_msg_timeout_t</strong> <var>timeout</var>, + <strong>mach_port_t</strong> <var>notify</var><strong>);</strong> + +<strong>mach_msg_return_t mach_msg_overwrite</strong> + <strong>(mach_msg_header_t*</strong> <var>send_msg</var>, + <strong>mach_msg_option_t</strong> <var>option</var>, + <strong>mach_msg_size_t</strong> <var>send_size</var>, + <strong>mach_msg_size_t</strong> <var>receive_limit</var>, + <strong>mach_port_t</strong> <var>receive_name</var>, + <strong>mach_msg_timeout_t</strong> <var>timeout</var>, + <strong>mach_port_t</strong> <var>notify</var>, + <strong>mach_msg_header_t</strong> <var>*receive_msg</var>, + <strong>mach_msg_size_t</strong> <var>receive_msg_size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>msg</var> +<dd> +[pointer to in/out structure containing random and reply rights] A +message buffer used by <strong>mach_msg</strong> both for send and receive. This must +be naturally aligned. +<p> +<dt> <var>send_msg</var> +<dd> +[pointer to in structure containing random and reply rights] The mes- +sage buffer to be sent. This must be naturally aligned. +<p> +<dt> <var>option</var> +<dd> +[in scalar] Message options are bit values, combined with bitwise-or. +One or both of MACH_SEND_MSG and MACH_RCV_MSG should be used. Other +options act as modifiers. +<p> +<dt> <var>send_size</var> +<dd> +[in scalar] When sending a message, specifies the size of the message +buffer to be sent (the size of the header and body) in +bytes. Otherwise zero should be supplied. +<p> +<dt> <var>receive_limit</var> +<dd> +[in scalar] When receiving a message, specifies the maximum size of +the msg or receive_msg buffer in bytes. Otherwise zero should be sup- +plied. +<p> +<dt> <var>receive_name</var> +<dd> +[in random right] When receiving a message, specifies the port or port +set. Otherwise MACH_PORT_NULL should be supplied. +<p> +<dt> <var>timeout</var> +<dd> +[in scalar] When using the MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT +options, specifies the time in milliseconds to wait before giving +up. Otherwise MACH_MSG_TIMEOUT_NONE should be supplied. +<p> +<dt> <var>notify</var> +<dd> +[in notify receive right] When using the MACH_SEND_CANCEL and +MACH_RCV_NOTIFY options, specifies the port used for the +notification. Otherwise MACH_PORT_NULL should be supplied. +<p> +<dt> <var>receive_msg</var> +<dd> +[pointer to in/out structure] A message buffer into which a message +(header and body) will be received. This must be naturally aligned. By +default (<strong>mach_msg</strong>), any received message will overwrite the send +message buffer. This buffer is in/out only if the MACH_RCV_OVERWRITE +option is used; otherwise this buffer is out only. +<p> +<dt> <var>receive_msg_size</var> +<dd> +[in scalar] When using the MACH_RCV_OVERWRITE option, specifies the +size (in bytes) of the receive "message" that is to be used by +<strong>mach_msg</strong> to indicate the disposition of received out-of-line regions. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_msg</strong> system call sends and receives Mach messages. Mach +messages contain data, which can include port rights and addresses of +large regions of memory. <strong>mach_msg</strong> uses the same buffer for sending and +receiving a message; the other calls permit separate send and receive +buffers (although they may be specified to be the same). +If the option argument contains MACH_SEND_MSG, the call sends a +message. The <var>send_size</var> argument specifies the size of the message +buffer (header and body) to send. The msgh_remote_port field of the +message header specifies the destination of the message. +If the option argument contains MACH_RCV_MSG, it receives a +message. The receive_limit argument specifies the size of a buffer +that will receive the message; messages that are larger are not +received. The receive_name argument specifies the port or port set +from which to receive. +<p> +If the option argument contains both MACH_SEND_MSG and MACH_RCV_MSG, +then <strong>mach_msg</strong> does both send and receive operations (in that +order). If the send operation encounters an error (any return code +other than MACH_MSG_SUCCESS), the call returns immediately +without attempting the receive operation. Semantically the combined +call is equivalent to separate send and receive calls, but it saves +a system call and enables other internal optimizations. + +If the option argument specifies neither MACH_SEND_MSG nor +MACH_RCV_MSG, <strong>mach_msg</strong> does nothing. +Some options, like MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT, share a +supporting argument. If these options are used together, they make +independent use of the supporting argument's value. +<h3>NOTES</h3> +<p> +The Mach kernel provides message-oriented, capability-based +inter-process communication. The inter-process communication (IPC) +primitives efficiently support many different styles of interaction, +including remote procedure calls, object-oriented distributed +programming, streaming of data, and sending very large amounts of +data. +<h4>Major Concepts</h4> +<p> +The IPC primitives operate on three abstractions: messages, ports, and +port sets. User tasks access all other kernel services and +abstractions via the IPC primitives. +<p> +The message primitives let tasks send and receive messages. Tasks send +messages to ports. Messages sent to a port are delivered reliably +(messages may not be lost) and are received in the order in which they +were sent via send rights by a given sending task (or a given +kernel). (Messages sent to send-once rights are unordered.) +<p> +Messages +contain a fixed-size header and a variable-sized message body +containing kernel and user data, and a variable-size trailer of kernel +appended message attributes. The header describes the destination +and the size of the message (header plus body). The message body +contains descriptions of additional port rights to be transmitted, +descriptions of "out-of-line" memory regions to be sent and a +variable amount of user data, which typically includes type conversion +information. The out-of-line memory regions (including out-of-line +port arrays) are (typically) disjoint from the message body. +The IPC implementation makes use of the VM system to efficiently +transfer large amounts of data. The message can contain the addresses +of regions of the sender's address space which should be transferred +as part of the message. +<p> +When a task receives a message containing +such out-of-line regions of data, the data can appear in unused +portions or overwrite an existing portion of the receiver's address +space (depending on the requested receive options). Under favorable +circumstances, the transmission of out-of-line data is optimized so +that sender and receiver share the physical pages of data +copy-on-write, and no actual data copy occurs unless the pages are +written. Regions of memory up to 4 gigabytes may be sent in this +manner. +<p> +Ports hold a queue of messages. Tasks operate on a port to send and +receive messages by exercising capabilities (rights) for the +port. Multiple tasks can hold send rights for a port. +Tasks can also +hold send-once rights, which grant the ability to send a single +message. Only one task can hold the receive capability (receive +right) for a port. +<p> +Port rights can be transferred between tasks via +messages. The sender of a message can specify in the message that the +message contains a port right. If a message contains a receive right +for a port, the receive right is removed from the sender of the +message and transferred to the receiver of the +message. While the receive right is in transit, tasks holding send +rights can still send messages to the port, and they are queued until +a task acquires the receive right and uses it to receive the messages. +<p> +Tasks can receive messages from ports and port sets. The port set +abstraction allows a single thread to wait for a message from any of +several ports. Tasks manipulate port sets with a port set name, +which is taken from the same name space as are the port rights. The +port-set name may not be transferred in a message. A port set holds +receive rights, and a receive operation on a port set blocks waiting +for a message sent to any of the constituent ports. A port may not be- +long to more than one port set, and if a port is a member of a port +set, the holder of the receive right can't receive directly from the +port. +<p> +Port rights are a secure, location-independent way of naming +ports. The port queue is a protected data structure, only accessible +via the kernel's exported message primitives. Rights are also +protected by the kernel; there is no way for a malicious user task to +guess a port's internal name and send a message to a port to which it +shouldn't have access. Port rights do not carry any location in- +formation. When a receive right for a port moves from task to task, +and even between tasks on different machines, the send rights for +the port remain unchanged and continue to function. +<h4>Port Rights</h4> +<p> +Each task has its own space of port rights. Port rights are named with +positive (unsigned) integers. For all architectures, sizeof +(mach_port_t) = sizeof (mach_port_name_t) = sizeof (void*) and so user +space addresses may be used as port names, except for the reserved +values MACH_PORT_NULL (0) and MACH_PORT_DEAD (all 1 bits). When the +kernel chooses a name for a new right, however, it is free to pick any +unused name (one which denotes no right) in the space. +<p> +There are three basic kinds of rights: receive rights, send rights and +send-once rights. A port name can name any of these types of rights, +or name a port-set, be a dead name, or name nothing. Dead names are +not capabilities. They act as place-holders to prevent a name from +being otherwise used. +<p> +A port is destroyed, or dies, when its receive right is +de-allocated. When a port dies, send and send-once rights for the port +turn into dead names. Any messages queued at the port are destroyed, +which de-allocates the port rights and out-of-line memory in the +messages. +<p> +Each send-once right held by a task has a different name. In contrast, +when a task holds send rights or a receive right for a port, the +rights share a single name. +<p> +Tasks may hold multiple user-references for send rights. When a task +receives a send right which it already holds, the kernel increments +the right's user-reference count. When a task de-allocates a send +right, the kernel decrements its user-reference count, and the task +only loses the send right when the count goes to zero. +<p> +Send-once rights always have a user reference count of one. Tasks may +hold multiple user references for dead names. +Each send-once right generated guarantees the receipt of a single +message, either a message sent to that send-once right or, if the +send-once right is in any way destroyed, a send-once notification. +<p> +A message can carry port rights; the msgh_remote or msgh_local fields +in the message header or the disposition field in a message body +descriptor specify the type of port right and how the port right is to +be extracted from the caller. The values MACH_PORT_NULL and +MACH_PORT_DEAD are valid in place of a port right in a message body. +<p> +In a sent message, the following mach_msg_type_name_t values denote +port rights: +<dl> +<dt> MACH_MSG_TYPE_MAKE_SEND + <dd> +The message will carry a send right, but the caller must supply a +receive right. The send right is created from the receive right, and the +receive right's make-send count is incremented. +<dt> MACH_MSG_TYPE_COPY_SEND + <dd> +The message will carry a send right, and the caller must supply a send +right. The user reference count for the supplied send right is not +changed. The caller may also supply a dead name and the receiving +task will get MACH_PORT_DEAD. +<dt> MACH_MSG_TYPE_MOVE_SEND + <dd> +The message will carry a send right, and the caller must supply a send +right. The user reference count for the supplied send right is +decremented, and the right is destroyed if the count becomes +zero. Unless a receive right remains, the name becomes available for +recycling. The caller may also supply a dead name, which loses a user +reference, and the receiving task will get MACH_PORT_DEAD. +<dt> MACH_MSG_TYPE_MAKE_SEND_ONCE +<dd> +The message will carry a send-once right, but the caller must supply a +receive right. The send-once right is created from the receive right. +Note that send once rights can only be created from the receive right. +<dt> MACH_MSG_TYPE_MOVE_SEND_ONCE + <dd> +The message will carry a send-once right, and the caller must supply a +send-once right. The caller loses the supplied send-once right. The +caller may also supply a dead name, which loses a user reference, +and the receiving task will get MACH_PORT_DEAD. +<dt> MACH_MSG_TYPE_MOVE_RECEIVE + <dd> +The message will carry a receive right, and the caller must supply a +receive right. The caller loses the supplied receive right, but +retains any send rights with the same name. The make-send count and +sequence number of the receive right are reset to zero and +no-more-senders notification requests are cancelled (with a +send-once notification being sent to the no-more-senders notification +right), but the port retains other attributes like queued messages +and extant send and send-once rights. +If a message carries a send or send-once right, and the port dies +while the message is in transit, then the receiving task will get +MACH_PORT_DEAD instead of a right. + </dl> + <p> +The following mach_msg_type_name_t values in a received message +indicate that it carries port rights: + <dl> +<dt> MACH_MSG_TYPE_PORT_SEND + <dd> +This value is an alias for MACH_MSG_TYPE_MOVE_SEND. The +message carried a send right. If the receiving task already has send and/ +or receive rights for the port, then that name for the port will be reused. +Otherwise, the right will have a new, previously unused, name. If the +task already has send rights, it gains a user reference for the right (un- +less this would cause the user-reference count to overflow). Otherwise, +it acquires send rights, with a user-reference count of one. +<dt> MACH_MSG_TYPE_PORT_SEND_ONCE + <dd> +This value is an alias for MACH_MSG_TYPE_MOVE_SEND_ONCE. The message +carried a send-once right. The right will have a new, previously +unused, name. +<dt> MACH_MSG_TYPE_PORT_RECEIVE + <dd> +This value is an alias for MACH_MSG_TYPE_MOVE_RECEIVE. The message +carried a receive right. If the receiving task already has send rights +for the port, then that name for the port will be reused; otherwise, +the right will have a new, previously unused name. + </dl> + <p> +It is also possible to send a (nearly unbounded) array of port rights +"out-of-line". All of the rights named by the array must be of the +same type. The array is physically copied with the message body +proper. The array of port right (names) can be received by the +receiver using the same options available for out-of-line data +reception described below. +<h4>Memory</h4> + <p> +A message can contain one or more regions of the sender's address +space which are to be transferred as part of the message. The message +carries a logical copy of the memory. For this "out-of-line" memory, +the kernel can copy the data or use virtual memory techniques to defer +any actual page copies unless the sender or the receiver modifies +the data, the physical pages remain shared. +<p> + The sender of the message must explicitly request an out-of-line +transfer. Such a region is described as an arbitrary region of the +sender's address space. The sender always sees this memory as being +copied to the receiver. +<p> + For each region, the sender has a de-allocate option. If the option is +set and the out-of-line memory region is not null, then the region is +implicitly de-allocated from the sender, as if by vm_deallocate. In +particular, the start address is truncated down and the end address +rounded up so that every page overlapped by the memory region is +de-allocated (thereby possibly de-allocating more memory than is +effectively transmitted). The use of this option effectively changes +the memory copy to a memory movement. Aside from possibly optimizing +the sender's use of memory, the de-allocation option allows the kernel +to more efficiently handle the transfer of memory. + <p> +For each region, the sender has the choice of permitting the kernel to +choose a transmission strategy or the choice of requiring physical +copy: + <dl> +<dt> MACH_MSG_VIRTUAL_COPY + <dd> +In a sent message, this flag allows the kernel to choose any mechanism +to transmit the data. For large regions, this involves constructing a +virtual copy of the pages containing the region. The portion of the +first page preceding the data and the portion of the last page +following the data are not copied (and will appear as zero if the +virtual copy is dynamically allocated in the receiver). + <p> +In a received message, this flag indicates that the kernel transmitted +a virtual copy. Access to the received memory may involve interactions +with the memory manager managing the sender's original data. Integri- +ty-conscious receivers should exercise caution when dealing with out- +of-line memory from un-trustworthy sources. Receivers concerned about +deterministic access time should also exercise caution. The dynamic +allocation option guarantees that the virtual copy will not be di- +rectly referenced during the act of receiving the message. +<dt> MACH_MSG_PHYSICAL_COPY + <dd> +In a sent message, this flag requires that the kernel construct an +actual copy of the memory (either into wired kernel memory or default +memory managed space). There is a (fairly large) limit on the amount +of data that can be physically copied in a message. Port arrays always +assume this option when sent. + <p> +In a received message, this flag indicates that the kernel did +transmit a physical copy. + </dl> + <p> +The receiver has two options for the reception of out-of-line memory +(or "out-of-line" port arrays): allocation and overwrite. +In the absence of the MACH_RCV_OVERWRITE option, all out-of-line re- +gions are dynamically allocated. Allocated out-of-line memory arrives +somewhere in the receiver's address space as new memory. It has the +same inheritance and protection attributes as newly vm_allocate'ed +memory. The receiver has the responsibility of de-allocating (with +vm_deallocate) the memory when it is no longer needed. If the message +contains more than one region, each will be allocated its own region, +not necessarily contiguously. If the sender's data was transmitted as +a virtual copy the allocated region will have the same data alignment +within the page; otherwise, the received data will appear starting at +the beginning of a page. + <p> +If the MACH_RCV_OVERWRITE option is set, the receiver can specify how +each received region is to be processed (dynamically allocated as +described above, or written over existing memory). With this option, +the contents of the receive buffer (receive_msg) are examined by the +kernel. The kernel scans the descriptors in the receive buffer +"message" to determine how to handle each out-of-line region. (Note: +whereas receive_limit is the maximum size of the receive buffer, +receive_msg_size is the amount filled in with this "message".) The +kernel uses each out-of-line data descriptor (in order) to specify +the processing for each received data region in turn, each out-of-line +port array descriptor is used correspondingly. (Intermingled port +descriptors are ignored when matching descriptors between the +incoming message and the receive buffer list.) +<p> +The copy option in the +matching descriptor specifies the processing: + <dl> +<dt> MACH_MSG_OVERWRITE + <dd> +This flag indicates that the region should write over a specified +region of the receiver's address space, as indicated by the address +and size/ count fields of the descriptor. The full range overwritten +must already exist (be allocated or mapped) in the receiver's address +space. Depending on the nature of the data transmission this +overwrite may involve virtual memory manipulations or it may involve +actual data copy. +<dt> MACH_MSG_ALLOCATE + <dd> +This flag indicates that the region is to be dynamically allocated. No +other descriptor values are relevant. + </dl> + <p> +If not enough descriptors appear in the receive buffer to describe all +received regions, additional regions are dynamically allocated. If +the receiver specifies more descriptors than there are regions in the +received message, the additional descriptors are ignored (and do not +appear in the final received message). + <p> +Note that the receive buffer descriptors will be overwritten: +The size fields in descriptors will be updated (when scanned, they +specified the maximum sizes of regions, when received, they specify +the actual sizes of received regions). +The copy fields in descriptors will be updated (when scanned, they +specified allocate versus overwrite, when received, they indicate +whether the region was physically or virtually copied). +The descriptors may appear in different positions (given intermingled +port descriptors). +Descriptors that were not used (because there were not that many +received regions) will be discarded. + <p> +Null out-of-line memory is legal. If the out-of-line region size is +zero, then the region's specified address is ignored. A receive +allocated null out-of-line memory region always has a zero address. +Unaligned addresses and region sizes that are not page multiples are +legal. A received message can also contain regions with unaligned +addresses and sizes which are not multiples of the page size. +<h4>Message Send</h4> + <p> +The send operation queues a message to a port. The message carries a +copy of the caller's data. After the send, the caller can freely +modify the message buffer or the out-of-line memory regions and the +message contents will remain unchanged. + <p> +The message carries with it the security ID of the sender, which the +receiver can request in the message trailer. + <p> +Message delivery is reliable and sequenced. Reception of a message +guarantees that all messages previously sent to the port by a single +task (or a single kernel) via send rights have been received and that +they are received in the order in which they were sent. Messages sent +to send-once rights are unordered. + <p> +If the destination port's queue is full, several things can happen. If +the message is sent to a send-once right (msgh_remote_port carries a +send-once right), then the kernel ignores the queue limit and delivers +the message. Otherwise the caller blocks until there is room in the +queue, unless the MACH_SEND_TIMEOUT option is used. If a port has +several blocked senders, then any of them may queue the next message +when space in the queue becomes available, with the proviso that a +blocked sender will not be indefinitely starved. +These options modify MACH_SEND_MSG. If MACH_SEND_MSG is not also +specified, they are ignored. +<dl> +<dt> MACH_SEND_TIMEOUT + <dd> +The timeout argument should specify a maximum time (in milliseconds) +for the call to block before giving up. If the message can't be queued +before the timeout interval elapses, then the call returns +MACH_SEND_TIMED_OUT. A zero timeout is legitimate. +<dt> MACH_SEND_INTERRUPT + <dd> +If specified, the <strong>mach_msg</strong> call will return +MACH_SEND_INTERRUPTED if a software interrupt aborts the call. +Otherwise, the send operation will be retried. +<dt> MACH_SEND_TRAILER + <dd> +If set, the kernel, instead of determining the message attributes +itself, will accept a formatted message trailer from the sender. The +supplied trailer must be of the latest version supported by the +kernel, and must contain all message attributes defined by the +kernel. Only tasks with a security ID of KERNEL_SECURITY_ID can use +this option; the intended use of this option is in support of the +Net Message server. The trailer must follow the message in memory as +it would appear in a received message. (The send_size argument to +<strong>mach_msg</strong> still indicates the size of the message proper, not including +this trailer.) + </dl> + <p> +The queueing of a message carrying receive rights may create a +circular loop of receive rights and messages, which can never be +received. For example, a message carrying a receive right can be +sent to that receive right. This situation is not an error, but the +kernel will garbage-collect such loops, destroying the messages. +Some return codes, like MACH_SEND_TIMED_OUT, imply that the message +was almost sent, but could not be queued. In these situations, the +kernel tries to return the message contents to the caller with a +pseudo-receive operation. This prevents the loss of port rights or +memory which only exist in the message, for example, a receive right +which was moved into the message, or out-of-line memory sent with +the de-allocate option. + <p> +The intent of the pseudo-receive operation is to restore, as best as +possible, the state prior to attempting the send. This involves +restoring the port rights and out-of-line memory regions contained in +the message. The port right names and out-of-line addresses in the +message send buffer are updated to reflect the new values resulting +from their effective reception. The pseudo-receive handles the des- +tination and reply rights as any other rights; they are not reversed +as is the appearance in a normal received message. Also, no trailer is +appended to the message. After the pseudo-receive, the message is +ready to be resent. If the message is not resent, note that +out-of-line memory regions may have moved and some port rights may +have changed names. + <p> +Although unlikely, the pseudo-receive operation may encounter resource +shortages. This is similar to a MACH_RCV_BODY_ERROR return code from +a receive operation. When this happens, the normal send return codes +are augmented with the MACH_MSG_IPC_SPACE, MACH_MSG_VM_SPACE, +MACH_MSG_IPC_KERNEL and MACH_MSG_VM_KERNEL bits to indicate the +nature of the resource shortage. +<h4>Message Receive</h4> + <p> +The receive operation de-queues a message from a port. The receiving +task acquires the port rights and out-of-line memory regions carried +in the message. +The receive_name argument specifies a port or port set from which to +receive. If a port is specified, the caller must possess the receive +right for the port and the port must not be a member of a port set. If +no message is present, the call blocks, subject to the +MACH_RCV_TIMEOUT option. +<p> +If a port set is specified, the call will receive a message sent to +any of the member ports. It is permissible for the port set to have +no member ports, and ports may be added and removed while a receive +from the port set is in progress. The received message can come from +any of the member ports which have messages, with the proviso that a +member port with messages will not be indefinitely starved. The +msgh_local_port field in the received message header specifies from +which port in the port set the message came. +<p> +The receive_limit argument specifies the size of the caller's message +buffer (which must be big enough for the message header, body and +trailer); the msgh_size field of the received message indicates the +actual size of the received message header and body. The <strong>mach_msg</strong> call +will not receive a message larger than receive_limit. Messages that +are too large are destroyed, unless the MACH_RCV_LARGE option is used. +Following the received data, at the next natural boundary, is a +message trailer. The msgh_size field of the received message does not +include the length of this trailer; the trailer's length is given by +the msgh_trailer_size field within the trailer. The receiver of a +message is given a choice as to what trailer format is desired, and, +within that format, which of the leading trailer attributes are +desired (that is, to get trailer element three, the receiver must also +accept elements one and two). For any given trailer format (of which +there is currently only one), the trailer is compatibly extended by +adding additional elements to the end. +<p> +Received messages are stamped (in the trailer) with a sequence number, +taken from the port from which the message was received. (Messages +received from a port set are stamped with a sequence number from the +appropriate member port.) Newly created ports start with a zero +sequence number, and the sequence number is reset to zero whenever the +port's receive right moves between tasks. When a message is de-queued +from the port, it is stamped with the port's sequence number and the +port's sequence number is then incremented. (Note that this occurs +whether or not the receiver requests the sequence number in the trail- +er.) The de-queue and increment operations are atomic, so that +multiple threads receiving messages from a port can use the msgh_seqno +field to reconstruct the original order of the messages. +<p> +The destination and reply ports are reversed in a received message +header. The msgh_local_port field carries the name of the destination +port, from which the message was received, and the msgh_remote_port +field carries the reply port right. The bits in msgh_bits are also +reversed. The MACH_MSGH_BITS_LOCAL bits have a value of +MACH_MSG_TYPE_PORT_SEND_ONCE or MACH_MSG_TYPE_PORT_SEND depending on +the type of right to which the message was sent. The +MACH_MSGH_BITS_REMOTE bits describe the reply port right. +<p> +A received message can contain port rights and out-of-line memory. The +msgh_local_port field does not carry a port right; the act of +receiving the message consumes the send or send-once right for the +destination port. The msgh_remote_port field does carry a port right, +and the message can carry additional port rights and memory if the +MACH_MSGH_BITS_COMPLEX bit is set. Received port rights and memory +should be consumed or de-allocated in some fashion. +In almost all cases, msgh_local_port will specify the name of a +receive right, either receive_name, or, if receive_name is a port +set, a member of receive_name. +<p> +If other threads are concurrently +manipulating the receive right, the situation is more complicated. If +the receive right is renamed during the call, then msgh_local_port +specifies the right's new name. If the caller loses the receive right +after the message was de-queued from it, then <strong>mach_msg</strong> will proceed +instead of returning MACH_RCV_PORT_DIED. If the receive right was +destroyed, then msgh_local_port specifies MACH_PORT_DEAD. If the +receive right still exists, but isn't held by the caller, then +msgh_local_port specifies MACH_PORT_NULL. +<p> +The following options modify MACH_RCV_MSG. If MACH_RCV_MSG is not also +specified, they are ignored. +<dl> +<dt> MACH_RCV_TIMEOUT + <dd> +The timeout argument should specify a maximum time (in milliseconds) +for the call to block before giving up. If no message arrives before +the timeout interval elapses, then the call returns +MACH_RCV_TIMED_OUT. A zero timeout is legitimate. +<dt> MACH_RCV_NOTIFY + <dd> +The notify argument should specify a receive right for a notify +port. If receiving the reply port creates a new port right in the +caller, then the notify port is used to request a dead-name +notification for the new port right. +<dt> MACH_RCV_INTERRUPT + <dd> +If specified, the <strong>mach_msg</strong> call will return MACH_RCV_INTERRUPTED if a +software interrupt aborts the call. Otherwise, the receive operation +will be retried. +<dt> MACH_RCV_OVERWRITE + <dd> +If specified, the message buffer specified by receive_msg (or msg), of +length receive_msg_size, will be scanned for out-of-line descriptors to +specify the processing to be done when receiving out-of-line regions. +This option is only allowed for <strong>mach_msg_overwrite</strong>. +<dt> MACH_RCV_LARGE + <dd> +If the message is larger than receive_limit or an out-of-line region +is larger than the size allowed by a corresponding receive descriptor +(MACH_RCV_OVERWRITE), the message remains queued instead of being +destroyed. If the header, trailer and body would not fit into +receive_limit, only the message header (mach_msg_header) and trailer +header (mach_msg_trailer) are returned with the actual size of the +message returned in the msgh_size field, the actual size of the +trailer returned in the msgh_trailer_size field and an error return +value of MACH_RCV_TOO_LARGE. If receive_limit is sufficient but an +out-of-line descriptor is not, the message header, trailer and body +are received, with out-of-line descriptors set to indicate the +nature and size of the out-of-line regions, with an error return of +MACH_RCV_SCATTER_SMALL. No out-of-line regions or port rights +(including the reply right) will be received. If this option is not +specified, messages too large will be de-queued and then destroyed; +the caller receives the message header, with all fields correct, +including the destination port but excepting the reply port, which is +MACH_PORT_NULL and an empty (no additional element) message trailer. +<dt> MACH_RCV_TRAILER_TYPE(value) + <dd> +This macro encodes the type of trailer the kernel must return with the +message. If the kernel does not recognize this type, it returns +MACH_RCV_INVALID_TRAILER. Currently, only MACH_MSG_TRAILER_FORMAT_0 is +supported. +<dt> MACH_RCV_TRAILER_ELEMENTS(value) + <dd> +This macro encodes the number of trailer elements desired. If the ker- +nel does not support this number for the requested trailer type, the +kernel returns MACH_RCV_INVALID_TRAILER. Zero is a legal value. + </dl> + <p> + The following trailer elements are supported: + <dl> +<dt> MACH_RCV_TRAILER_SEQNO + <dd> +Returns the sequence number of the message relative to its port. This +value is of type mach_port_seqno_t. +<dt> MACH_RCV_TRAILER_SENDER + <dd> +Returns the security ID of the task that sent the message. This value +is of type security_id_t. + </dl> + <p> +If a resource shortage prevents the reception of a port right, the +port right is destroyed and the caller sees the name +MACH_PORT_NULL. If a resource shortage prevents the reception of an +out-of-line memory region, the region is destroyed and the caller sees +a zero address. In addition, the corresponding element in the size +array is set to zero. A task never receives port rights or memory for +which it is not told. + <p> +The MACH_RCV_HEADER_ERROR return code indicates a resource shortage +in the reception of the message header. The reply port and all port +rights and memory in the message are destroyed. The caller receives +the message header with all fields correct except for the reply +port. + <p> +The MACH_RCV_BODY_ERROR return code indicates a resource shortage in +the reception of the message body. The message header, including the +reply port, is correct. The kernel attempts to transfer all port +rights and memory regions in the body, and only destroys those that +can't be transferred. +<h4>Atomicity</h4> + <p> +The <strong>mach_msg</strong> call handles port rights in the message header +atomically. Out-of-line memory and port rights in the message body do +not enjoy this atomicity guarantee. These elements may be processed +front-to-back, back-to-front, in some random order, or even +atomically. + <p> +For example, consider sending a message with the destination port +specified as MACH_MSG_TYPE_MOVE_SEND and the reply port specified as +MACH_MSG_TYPE_COPY_SEND. The same send right, with one user-refer- +ence, is supplied for both the msgh_remote_port and msgh_local_port +fields. Because <strong>mach_msg</strong> processes the port rights atomically, this +succeeds. If msgh_remote_port were processed before msgh_local_port, +then <strong>mach_msg</strong> would return MACH_SEND_INVALID_REPLY in this situation. + <p> +On the other hand, suppose the destination and reply port are both +specified as MACH_MSG_TYPE_MOVE_SEND, and again the same send right +with one user-reference is supplied for both. Now the send operation +fails, but because it processes the rights atomically, <strong>mach_msg</strong> can +return either MACH_SEND_INVALID_DEST or MACH_SEND_INVALID_REPLY. +<p> +For example, consider receiving a message at the same time another +thread is deallocating the destination receive right. Suppose the +reply port field carries a send right for the destination port. If the +de-allocation happens before the dequeuing, the receiver gets +MACH_RCV_PORT_DIED. If the de-allocation happens after the receive, +the msgh_local_port and the msgh_remote_port fields both specify +the same right, which becomes a dead name when the receive right is +de-allocated. If the de-allocation happens between the de-queue and +the receive, the msgh_local_port and msgh_remote_port fields both +specify MACH_PORT_DEAD. Because the rights are processed atomically, +it is not possible for just one of the two fields to hold +MACH_PORT_DEAD. +<p> +The MACH_RCV_NOTIFY option provides a more likely example. Suppose a +message carrying a send-once right reply port is received with +MACH_RCV_NOTIFY at the same time the reply port is destroyed. If the +reply port is destroyed first, then msgh_remote_port specifies +MACH_PORT_DEAD and the kernel does not generate a dead-name +notification. If the reply port is destroyed after it is received, +then msgh_remote_port specifies a dead name for which the kernel +generates a dead-name notification. Either the reply port is dead on +arrival or notification is requested. +<h4>Implementation</h4> +<p> +<strong>mach_msg</strong> and <strong>mach_msg_overwrite</strong> are wrappers for a system call. They +have the responsibility for repeating the interrupted system call. +<h3>CAUTIONS</h3> +<p> +If MACH_RCV_TIMEOUT is used without MACH_RCV_INTERRUPT, then the +timeout duration might not be accurate. When the call is interrupted +and automatically retried, the original timeout is used. If +interrupts occur frequently enough, the timeout interval might never +expire. MACH_SEND_TIMEOUT without MACH_SEND_INTERRUPT suffers from the +same problem. +<h3>RETURN VALUES</h3> +<p> +The send operation can generate the following return codes. These +return codes imply that the call did nothing: +<dl> +<p> +<dt> MACH_SEND_MSG_TOO_SMALL + <dd> +The specified send_size was smaller than the minimum size for a +message. +<p> +<dt> MACH_SEND_NO_BUFFER + <dd> +A resource shortage prevented the kernel from allocating a message +buffer. +<p> +<dt> MACH_SEND_INVALID_DATA + <dd> +The supplied message buffer was not readable. +<p> +<dt> MACH_SEND_INVALID_HEADER + <dd> +The msgh_bits value was invalid. +<p> +<dt> MACH_SEND_INVALID_DEST + <dd> +The msgh_remote_port value was invalid. +<p> +<dt> MACH_SEND_INVALID_NOTIFY + <dd> +When using MACH_SEND_CANCEL, the notify argument did not +denote a valid receive right. +<p> +<dt> MACH_SEND_INVALID_REPLY + <dd> +The msgh_local_port value was invalid. +<p> +<dt> MACH_SEND_INVALID_TRAILER + <dd> +The trailer to be sent does not correspond to the current kernel format, +or the sending task does not have the privilege to supply the message +attributes. + </dl> + <p> +These return codes imply that some or all of the message was destroyed: + <dl> +<p> +<dt> MACH_SEND_INVALID_MEMORY + <dd> +The message body specified out-of-line data that was not readable. +<p> +<dt> MACH_SEND_INVALID_RIGHT + <dd> +The message body specified a port right which the caller didn't possess. +<p> +<dt> MACH_SEND_INVALID_TYPE + <dd> +A kernel processed descriptor was invalid. +<p> +<dt> MACH_SEND_MSG_TOO_SMALL + <dd> +The last data item in the message ran over the end of the message. + </dl> + <p> +These return codes imply that the message was returned to the caller with a +pseudo-receive operation: + <dl> +<p> +<dt> MACH_SEND_TIMED_OUT + <dd> +The timeout interval expired. +<p> +<dt> MACH_SEND_INTERRUPTED + <dd> +A software interrupt occurred. + </dl> + <p> +This return code implies that the message was queued: + <dl> +<p> +<dt> MACH_MSG_SUCCESS + <dd> +The message was queued. + </dl> + <p> +The receive operation can generate the following return codes. These return +codes imply that the call did not de-queue a message: + <dl> +<p> +<dt> MACH_RCV_INVALID_NAME + <dd> +The specified receive_name was invalid. +<p> +<dt> MACH_RCV_IN_SET + <dd> +The specified port was a member of a port set. +<p> +<dt> MACH_RCV_TIMED_OUT + <dd> +The timeout interval expired. +<p> +<dt> MACH_RCV_INTERRUPTED + <dd> +A software interrupt occurred. +<p> +<dt> MACH_RCV_PORT_DIED + <dd> +The caller lost the rights specified by receive_name. +<p> +<dt> MACH_RCV_PORT_CHANGED + <dd> +receive_name specified a receive right which was moved into a port set +during the call. +<p> +<dt> MACH_RCV_TOO_LARGE + <dd> +When using MACH_RCV_LARGE, the message was larger than +receive_limit. The message is left queued, and its actual size is +returned in the message header/message body. +<p> +<dt> MACH_RCV_SCATTER_SMALL + <dd> +When using MACH_RCV_LARGE with MACH_RCV_OVERWRITE, one or more scatter +list descriptors specified an overwrite region smaller than the +corresponding incoming region. The message is left queued, and the +proper descriptors are returned in the message header/message body. +<p> +<dt> MACH_RCV_INVALID_TRAILER + <dd> +The trailer type desired, or the number of trailer elements desired, is +not supported by the kernel. + </dl> + <p> +These return codes imply that a message was de-queued and destroyed: + <dl> +<p> +<dt> MACH_RCV_HEADER_ERROR + <dd> +A resource shortage prevented the reception of the port rights in the +message header. +<p> +<dt> MACH_RCV_INVALID_NOTIFY + <dd> +When using MACH_RCV_NOTIFY, the notify argument did not denote a +valid receive right. +<p> +<dt> MACH_RCV_INVALID_DATA + <dd> +The specified message buffer was not writable. +<p> +<dt> MACH_RCV_TOO_LARGE + <dd> +When not using MACH_RCV_LARGE, a message larger than +receive_limit was de-queued and destroyed. +<p> +<dt> MACH_RCV_SCATTER_SMALL + <dd> +When not using MACH_RCV_LARGE with MACH_RCV_OVERWRITE, one or more +scatter list descriptors specified an overwrite region smaller than +the corresponding incoming region. The message was de-queued and +destroyed. +<p> +<dt> MACH_RCV_OVERWRITE_ERROR + <dd> +A region specified by a receive overwrite descriptor +(MACH_RCV_OVERWRITE) was not allocated or could not be written. +<p> +<dt> MACH_RCV_INVALID_TYPE + <dd> +When using MACH_RCV_OVERWRITE, one or more scatter list descriptors +did not have the type matching the corresponding incoming message +descriptor or had an invalid copy (disposition) field. +<p> +<dt> MACH_RCV_LIMITS + <dd> +The combined size of all out-of-line memory regions or the total num- +ber of port rights in the message exceeds the limit set for the port. +These return codes imply that a message was received: +<p> +<dt> MACH_RCV_BODY_ERROR + <dd> +A resource shortage prevented the reception of a port right or out-of- +line memory region in the message body. +<p> +<dt> MACH_MSG_SUCCESS + <dd> +A message was received. + </dl> + <p> +Resource shortages can occur after a message is de-queued, while +transferring port rights and out-of-line memory regions to the +receiving task. The <strong>mach_msg</strong> call returns MACH_RCV_HEADER_ERROR or +MACH_RCV_BODY_ERROR in this situation. These return codes always carry + extra bits (bitwise-or'ed) that indicate the nature of the resource +shortage: + <dl> +<p> +<dt> MACH_MSG_IPC_SPACE + <dd> +There was no room in the task's IPC name space for another port name. +<p> +<dt> MACH_MSG_VM_SPACE + <dd> +There was no room in the task's VM address space for an out-of-line +memory region. +<p> +<dt> MACH_MSG_IPC_KERNEL + <dd> +A kernel resource shortage prevented the reception of a port right. +<p> +<dt> MACH_MSG_VM_KERNEL + <dd> +A kernel resource shortage prevented the reception of an out-of-line +memory region. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_allocate.html"><strong>vm_allocate</strong></a>, +<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, +<a href="vm_write.html"><strong>vm_write</strong></a>, +<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, +<p> +Data Structures: +mach_msg_header. diff --git a/osfmk/man/mach_msg_descriptor.html b/osfmk/man/mach_msg_descriptor.html index a44bf90bb..126527476 100755 --- a/osfmk/man/mach_msg_descriptor.html +++ b/osfmk/man/mach_msg_descriptor.html @@ -1 +1,116 @@ -<h2>mach_msg_descriptor</h2> <hr> <p> <strong>Structure</strong> - Specifies operations that must be performed on a given IPC message element. <h3>SYNOPSIS</h3> <pre> <strong>typedef struct</strong> <strong>{</strong> <strong>void*</strong> <var>pad1</var><strong>;</strong> <strong>mach_msg_size_t</strong> <var>pad2</var><strong>;</strong> <strong>unsigned int</strong> <var>pad3</var><strong> : 24;</strong> <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong> <strong>} mach_msg_type_descriptor_t;</strong> <strong>typedef struct</strong> <strong>{</strong> <strong>mach_port_t</strong> <var>name</var><strong>;</strong> <strong>mach_msg_size_t</strong> <var>pad1</var><strong>;</strong> <strong>unsigned int</strong> <var>pad2</var><strong> : 16;</strong> <strong>mach_msg_type_name_t</strong> <var>disposition</var><strong> : 8;</strong> <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong> <strong>} mach_msg_port_descriptor_t;</strong> <strong>typedef struct</strong> <strong>{</strong> <strong>void*</strong> <var>address</var><strong>;</strong> <strong>mach_msg_size_t</strong> <var>size</var><strong>;</strong> <strong>boolean_t</strong> <var>deallocate</var><strong> : 8;</strong> <strong>mach_msg_copy_options_t</strong> <var>copy</var><strong> : 8;</strong> <strong>unsigned int</strong> <var>pad1</var><strong> : 8;</strong> <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong> <strong>} mach_msg_ool_descriptor_t;</strong> <strong>typedef struct</strong> <strong>{</strong> <strong>void*</strong> <var>address</var><strong>;</strong> <strong>mach_msg_size_t</strong> <var>count</var><strong>;</strong> <strong>boolean_t</strong> <var>deallocate</var><strong> : 8;</strong> <strong>mach_msg_copy_options_t</strong> <var>copy</var><strong> : 8;</strong> <strong>mach_msg_type_name_t</strong> <var>disposition</var><strong> : 8;</strong> <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong> <strong>} mach_msg_ool_ports_descriptor_t;</strong> <strong>typedef union</strong> <strong>{</strong> <strong>mach_msg_port_descriptor_t</strong> <var>port</var><strong>;</strong> <strong>mach_msg_ool_descriptor_t</strong> <var>out_of_line</var><strong>;</strong> <strong>mach_msg_ool_ports_descriptor_t</strong> <var>ool_ports</var><strong>;</strong> <strong>mach_msg_type_descriptor_t</strong> <var>type</var><strong>;</strong> <strong>} mach_msg_descriptor_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>name</var> <dd> For single port descriptors, the name of the port whose right is being sent. <p> <dt> <var>disposition</var> <dd> For single port or out-of-line port array descriptors, the IPC processing to be done for the rights for the named ports. <p> <dt> <var>address</var> <dd> For out-of-line data or port array descriptors, the address of the out-of-line data or port (name) array. <p> <dt> <var>size</var> <dd> For out-of-line data descriptors, the size of the out-of-line region, in bytes. <p> <dt> <var>deallocate</var> <dd> For out-of-line data descriptors, true if the set of pages containing the array should be de-allocated when the message is sent. <p> <dt> <var>copy</var> <dd> For out-of-line descriptors, a description of the method by which the data should be copied. <p> <dt> <var>count</var> <dd> For out-of-line port array descriptors, the number of port names in the array. <p> <dt> <var>type</var> <dd> For any type of descriptor, the type of descriptor. <p> <dt> <var>port</var> <dd> A descriptor that describes a single port right. <p> <dt> <var>out_of_line</var> <dd> A descriptor that describes an out-of-line data array. <p> <dt> <var>ool_ports</var> <dd> A descriptor that describes an out-of-line port array. </dl> <h3>DESCRIPTION</h3> <p> A <strong>mach_msg_descriptor</strong> structure describes the processing to be performed for an element of kernel-processed data in a Mach message. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_msg.html"><strong>mach_msg</strong></a>. <p> Data Structures: <a href="mach_msg_header.html"><strong>mach_msg_header</strong></a>. \ No newline at end of file +<h2>mach_msg_descriptor</h2> +<hr> +<p> +<strong>Structure</strong> - Specifies operations that must be performed on a given IPC message element. +<h3>SYNOPSIS</h3> +<pre> +<strong>typedef struct</strong> +<strong>{</strong> + <strong>void*</strong> <var>pad1</var><strong>;</strong> + <strong>mach_msg_size_t</strong> <var>pad2</var><strong>;</strong> + <strong>unsigned int</strong> <var>pad3</var><strong> : 24;</strong> + <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong> +<strong>} mach_msg_type_descriptor_t;</strong> + +<strong>typedef struct</strong> +<strong>{</strong> + <strong>mach_port_t</strong> <var>name</var><strong>;</strong> + <strong>mach_msg_size_t</strong> <var>pad1</var><strong>;</strong> + <strong>unsigned int</strong> <var>pad2</var><strong> : 16;</strong> + <strong>mach_msg_type_name_t</strong> <var>disposition</var><strong> : 8;</strong> + <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong> +<strong>} mach_msg_port_descriptor_t;</strong> + +<strong>typedef struct</strong> +<strong>{</strong> + <strong>void*</strong> <var>address</var><strong>;</strong> + <strong>mach_msg_size_t</strong> <var>size</var><strong>;</strong> + <strong>boolean_t</strong> <var>deallocate</var><strong> : 8;</strong> + <strong>mach_msg_copy_options_t</strong> <var>copy</var><strong> : 8;</strong> + <strong>unsigned int</strong> <var>pad1</var><strong> : 8;</strong> + <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong> +<strong>} mach_msg_ool_descriptor_t;</strong> + +<strong>typedef struct</strong> +<strong>{</strong> + <strong>void*</strong> <var>address</var><strong>;</strong> + <strong>mach_msg_size_t</strong> <var>count</var><strong>;</strong> + <strong>boolean_t</strong> <var>deallocate</var><strong> : 8;</strong> + <strong>mach_msg_copy_options_t</strong> <var>copy</var><strong> : 8;</strong> + <strong>mach_msg_type_name_t</strong> <var>disposition</var><strong> : 8;</strong> + <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong> +<strong>} mach_msg_ool_ports_descriptor_t;</strong> + +<strong>typedef union</strong> +<strong>{</strong> + <strong>mach_msg_port_descriptor_t</strong> <var>port</var><strong>;</strong> + <strong>mach_msg_ool_descriptor_t</strong> <var>out_of_line</var><strong>;</strong> + <strong>mach_msg_ool_ports_descriptor_t</strong> <var>ool_ports</var><strong>;</strong> + <strong>mach_msg_type_descriptor_t</strong> <var>type</var><strong>;</strong> +<strong>} mach_msg_descriptor_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>name</var> +<dd> +For single port descriptors, the name of the port whose right is being +sent. + <p> +<dt> <var>disposition</var> +<dd> +For single port or out-of-line port array descriptors, the IPC processing +to be done for the rights for the named ports. + <p> +<dt> <var>address</var> +<dd> +For out-of-line data or port array descriptors, the address of the +out-of-line data or port (name) array. + <p> +<dt> <var>size</var> +<dd> +For out-of-line data descriptors, the size of the out-of-line region, in +bytes. + <p> +<dt> <var>deallocate</var> +<dd> +For out-of-line data descriptors, true if the set of pages containing the +array should be de-allocated when the message is sent. + <p> +<dt> <var>copy</var> +<dd> +For out-of-line descriptors, a description of the method by which the +data should be copied. + <p> +<dt> <var>count</var> +<dd> +For out-of-line port array descriptors, the number of port names in the +array. + <p> +<dt> <var>type</var> +<dd> +For any type of descriptor, the type of descriptor. + <p> +<dt> <var>port</var> +<dd> +A descriptor that describes a single port right. + <p> +<dt> <var>out_of_line</var> +<dd> +A descriptor that describes an out-of-line data array. + <p> +<dt> <var>ool_ports</var> +<dd> +A descriptor that describes an out-of-line port array. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>mach_msg_descriptor</strong> structure describes the processing +to be performed +for an element of kernel-processed data in a Mach message. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_msg.html"><strong>mach_msg</strong></a>. +<p> +Data Structures: +<a href="mach_msg_header.html"><strong>mach_msg_header</strong></a>. diff --git a/osfmk/man/mach_msg_header.html b/osfmk/man/mach_msg_header.html index 891598f1b..ff229d88e 100755 --- a/osfmk/man/mach_msg_header.html +++ b/osfmk/man/mach_msg_header.html @@ -1 +1,183 @@ -<h2>mach_msg_header</h2> <hr> <p> <strong>Structure</strong> - Specifies the content of an IPC message header. <h3>SYNOPSIS</h3> <pre> <strong>typedef struct</strong> <strong>{</strong> <strong>mach_msg_bits_t </strong> <var>msgh_bits</var><strong>;</strong> <strong>mach_msg_size_t</strong> <var>msgh_size</var><strong>;</strong> <strong>mach_port_t</strong> <var>msgh_remote_port</var><strong>;</strong> <strong>mach_port_t</strong> <var>msgh_local_port</var><strong>;</strong> <strong>mach_msg_size_t</strong> <var>msgh_reserved</var><strong>;</strong> <strong>mach_msg_id_t</strong> <var>msgh_id</var><strong>;</strong> <strong>} mach_msg_header_t;</strong> <strong>typedef struct</strong> <strong>{</strong> <strong>mach_msg_size_t</strong> <var>msgh_descriptor_count</var><strong>;</strong> <strong>} mach_msg_body_t;</strong> <strong>typedef struct</strong> <strong>{</strong> <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong> <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong> <strong>} mach_msg_trailer_t;</strong> <strong>typedef struct</strong> <strong>{</strong> <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong> <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong> <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong> <strong>} mach_msg_seqno_trailer_t;</strong> <strong>typedef struct</strong> <strong>{</strong> <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong> <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong> <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong> <strong>security_token_t</strong> <var>msgh_sender</var><strong>;</strong> <strong>} mach_msg_security_trailer_t;</strong> <strong>typedef struct</strong> <strong>{</strong> <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong> <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong> <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong> <strong>security_token_t</strong> <var>msgh_sender</var><strong>;</strong> <strong>unsigned int</strong> <var>dipc_sender_kmsg</var><strong>;</strong> <strong>} mach_msg_dipc_trailer_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>msgh_bits</var> <dd> This field specifies the following properties of the message: <dl> <p> <dt> <strong>MACH_MSGH_BITS_REMOTE_MASK</strong> <dd> Encodes <var>mach_msg_type_name_t</var> values that specify the port rights in the <var>msgh_remote_port</var> field. The value must specify a send or send-once right for the destination of the message. <p> <dt> <strong>MACH_MSGH_BITS_LOCAL_MASK</strong> <dd> Encodes <var>mach_msg_type_name_t</var> values that specify the port rights in the <var>msgh_local_port</var> field. If the value doesn't specify a send or send-once right for the message's reply port, it must be zero and <var>msgh_local_port</var> must be <strong>MACH_PORT_NULL</strong>. <p> <dt> <strong>MACH_MSGH_BITS_COMPLEX</strong> <dd> The complex bit must be specified if the message body contains additional port rights or out-of-line memory regions. <p> <dt> <strong>MACH_MSGH_BITS_REMOTE</strong>(<var>bits</var>) <dd> This macro returns the appropriate <var>mach_msg_type_name_t</var> values, given a <var>msgh_bits</var> value. <p> <dt> <strong>MACH_MSGH_BITS_LOCAL</strong>(<var>bits</var>) <dd> This macro returns the appropriate <var>mach_msg_type_name_t</var> values, given a <var>msgh_bits</var> value. <p> <dt> <strong>MACH_MSGH_BITS</strong>(<var>remote</var>, <var>local</var>) <dd> This macro constructs a value for <var>msgh_bits</var>, given two <var>mach_msg_type_name_t</var> values. </dl> <p> <dt> <var>msgh_size</var> <dd> This field is ignored on send (the size to send is specified by the <var>send_size</var> parameter to <strong>mach_msg</strong>); the field is set on receive to the sum of the message header and body sizes (in bytes). Note that this value may be different from the send size specified by the sender if the sender and receiver machines have differing sizes for port names, memory addresses or memory range sizes. <p> <dt> <var>msgh_remote_port</var> <dd> When sending, specifies the destination port of the message. The field must carry a legitimate send or send-once right for a port. When received, this field is swapped with <var>msgh_local_port</var>. <p> <dt> <var>msgh_local_port</var> <dd> When sending, specifies an auxiliary port right, which is conventionally used as a reply port by the recipient of the message. The field must carry a send right, a send-once right, <strong>MACH_PORT_NULL</strong>, or <strong>MACH_PORT_DEAD</strong>. When received, this field is swapped with <var>msgh_remote_port</var>. <p> <dt> <var>msgh_id</var> <dd> Not set or read by the <strong>mach_msg</strong> call. The conventional meaning is to convey an operation or function ID. <p> <dt> <var>msgh_descriptor_count</var> <dd> The number of descriptors of kernel processed data (port rights and out-of-line data). <p> <dt> <var>msgh_trailer_type</var> <dd> An identifier of the trailer version. Different values indicate not necessarily compatible trailer formats. The current (and only) trailer format is <strong>MACH_MSG_TRAILER_FORMAT_0</strong>. There is currently only one attribute defined within this trailer type: the sender's identity. <p> <dt> <var>msgh_trailer_size</var> <dd> The length, in bytes, of the message trailer, including the trailer type and length fields. <p> <dt> <var>msgh_seqno</var> <dd> The sequence number of this message relative to the port from which it is received. <p> <dt> <var>msgh_sender</var> <dd> The security ID of the sender of the message. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_msg_header</strong> structure defines the fixed size header of a Mach message. The header is followed by a message body containing data and port descriptors and zero or more data bytes. <p> If the <strong>MACH_MSGH_BITS_COMPLEX</strong> flag in the <var>msgh_bits</var> field is not set, then this is a simple message described by <strong>mach_msg_header_t</strong>. In this case, the header is immediately followed by untyped data. <p> If the complex flag is set, then this is a "complex" message consisting of a <strong>mach_msg_header_t</strong> structure followed by a <strong>mach_msg_body_t</strong> structure containing a count followed by an array of descriptors specifying the disposition (processing) to be performed for the out-of-line memory regions and additional port rights. <p> Following the header (and any kernel processed descriptors), at natural alignment can be additional (un-typed) data, up to the size of the message (<var>msgh_size</var>). This extra data typically carries information used to decode the data stream and out-of-line data. <p> At the next natural boundary following the message data is the message trailer (<strong>mach_msg_trailer_t</strong>). This structure indicates the type and length of the trailer. If the length is greater than sizeof (<strong>mach_msg_trailer_t</strong>), additional fields follow providing kernel-generated message attributes. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_msg.html"><strong>mach_msg</strong></a>. <p> Data Structures: <a href="mach_msg_descriptor.html"><strong>mach_msg_descriptor</strong></a>. \ No newline at end of file +<h2>mach_msg_header</h2> +<hr> +<p> +<strong>Structure</strong> - Specifies the content of an IPC message header. +<h3>SYNOPSIS</h3> +<pre> +<strong>typedef struct</strong> +<strong>{</strong> + <strong>mach_msg_bits_t </strong> <var>msgh_bits</var><strong>;</strong> + <strong>mach_msg_size_t</strong> <var>msgh_size</var><strong>;</strong> + <strong>mach_port_t</strong> <var>msgh_remote_port</var><strong>;</strong> + <strong>mach_port_t</strong> <var>msgh_local_port</var><strong>;</strong> + <strong>mach_msg_size_t</strong> <var>msgh_reserved</var><strong>;</strong> + <strong>mach_msg_id_t</strong> <var>msgh_id</var><strong>;</strong> +<strong>} mach_msg_header_t;</strong> + +<strong>typedef struct</strong> +<strong>{</strong> + <strong>mach_msg_size_t</strong> <var>msgh_descriptor_count</var><strong>;</strong> +<strong>} mach_msg_body_t;</strong> + +<strong>typedef struct</strong> +<strong>{</strong> + <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong> + <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong> +<strong>} mach_msg_trailer_t;</strong> + +<strong>typedef struct</strong> +<strong>{</strong> + <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong> + <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong> + <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong> +<strong>} mach_msg_seqno_trailer_t;</strong> + +<strong>typedef struct</strong> +<strong>{</strong> + <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong> + <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong> + <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong> + <strong>security_token_t</strong> <var>msgh_sender</var><strong>;</strong> +<strong>} mach_msg_security_trailer_t;</strong> + +<strong>typedef struct</strong> +<strong>{</strong> + <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong> + <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong> + <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong> + <strong>security_token_t</strong> <var>msgh_sender</var><strong>;</strong> + <strong>unsigned int</strong> <var>dipc_sender_kmsg</var><strong>;</strong> +<strong>} mach_msg_dipc_trailer_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>msgh_bits</var> +<dd> +This field specifies the following properties of the message: +<dl> + <p> +<dt> <strong>MACH_MSGH_BITS_REMOTE_MASK</strong> +<dd> +Encodes <var>mach_msg_type_name_t</var> values that specify the port +rights in the <var>msgh_remote_port</var> field. The value must specify +a send or send-once right for the destination of the message. + <p> +<dt> <strong>MACH_MSGH_BITS_LOCAL_MASK</strong> +<dd> +Encodes <var>mach_msg_type_name_t</var> values that specify the port +rights in the <var>msgh_local_port</var> field. If the value doesn't +specify a send or send-once right for the message's reply port, it +must be zero and <var>msgh_local_port</var> must be <strong>MACH_PORT_NULL</strong>. + <p> +<dt> <strong>MACH_MSGH_BITS_COMPLEX</strong> +<dd> +The complex bit must be specified if the message body +contains additional port rights or out-of-line memory regions. + <p> +<dt> <strong>MACH_MSGH_BITS_REMOTE</strong>(<var>bits</var>) +<dd> +This macro returns the appropriate <var>mach_msg_type_name_t</var> +values, given a <var>msgh_bits</var> value. + <p> +<dt> <strong>MACH_MSGH_BITS_LOCAL</strong>(<var>bits</var>) +<dd> +This macro returns the appropriate <var>mach_msg_type_name_t</var> +values, given a <var>msgh_bits</var> value. + <p> +<dt> <strong>MACH_MSGH_BITS</strong>(<var>remote</var>, <var>local</var>) +<dd> +This macro constructs a value for <var>msgh_bits</var>, given two +<var>mach_msg_type_name_t</var> values. +</dl> +<p> +<dt> <var>msgh_size</var> +<dd> +This field is ignored on send (the size to send is specified by the +<var>send_size</var> parameter to <strong>mach_msg</strong>); the field is set on +receive to the sum of +the message header and body sizes (in bytes). Note that this value may +be different from the send size specified by the sender if the sender and +receiver machines have differing sizes for port names, memory +addresses or memory range sizes. + <p> +<dt> <var>msgh_remote_port</var> +<dd> +When sending, specifies the destination port of the message. The field +must carry a legitimate send or send-once right for a port. When +received, this field is swapped with <var>msgh_local_port</var>. + <p> +<dt> <var>msgh_local_port</var> +<dd> +When sending, specifies an auxiliary port right, which is +conventionally used as a reply port by the recipient of the message. +The field must +carry a send right, a send-once right, <strong>MACH_PORT_NULL</strong>, or +<strong>MACH_PORT_DEAD</strong>. When received, this field is swapped with +<var>msgh_remote_port</var>. + <p> +<dt> <var>msgh_id</var> +<dd> +Not set or read by the <strong>mach_msg</strong> call. The conventional meaning is to +convey an operation or function ID. + <p> +<dt> <var>msgh_descriptor_count</var> +<dd> +The number of descriptors of kernel processed data (port rights and +out-of-line data). + <p> +<dt> <var>msgh_trailer_type</var> +<dd> +An identifier of the trailer version. Different values indicate not +necessarily compatible trailer formats. The current (and only) trailer format +is <strong>MACH_MSG_TRAILER_FORMAT_0</strong>. There is currently only one +attribute defined within this trailer type: the sender's identity. + <p> +<dt> <var>msgh_trailer_size</var> +<dd> +The length, in bytes, of the message trailer, including the trailer type +and length fields. + <p> +<dt> <var>msgh_seqno</var> +<dd> +The sequence number of this message relative to the port from which it +is received. + <p> +<dt> <var>msgh_sender</var> +<dd> +The security ID of the sender of the message. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_msg_header</strong> structure defines the fixed size header of a Mach +message. The header is followed by a message body containing data and port +descriptors and zero or more data bytes. +<p> +If the <strong>MACH_MSGH_BITS_COMPLEX</strong> flag in the <var>msgh_bits</var> field is not set, +then this is a simple message described by <strong>mach_msg_header_t</strong>. +In this case, the header is immediately followed by untyped data. +<p> +If the complex flag is set, then this is a "complex" message consisting of a +<strong>mach_msg_header_t</strong> structure followed by a <strong>mach_msg_body_t</strong> structure +containing a count followed by an array of descriptors specifying +the disposition +(processing) to be performed for the out-of-line memory regions and additional +port rights. +<p> +Following the header (and any kernel processed descriptors), at natural +alignment can be additional (un-typed) data, up to the size of the message +(<var>msgh_size</var>). This extra data typically carries information +used to decode the data stream and out-of-line data. +<p> +At the next natural boundary following the message data is the message trailer +(<strong>mach_msg_trailer_t</strong>). This structure indicates the type and length of the +trailer. If the length is greater than sizeof (<strong>mach_msg_trailer_t</strong>), +additional fields +follow providing kernel-generated message attributes. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_msg.html"><strong>mach_msg</strong></a>. +<p> +Data Structures: +<a href="mach_msg_descriptor.html"><strong>mach_msg_descriptor</strong></a>. + diff --git a/osfmk/man/mach_port_allocate.html b/osfmk/man/mach_port_allocate.html index 997830684..9b802f24b 100755 --- a/osfmk/man/mach_port_allocate.html +++ b/osfmk/man/mach_port_allocate.html @@ -1 +1,84 @@ -<h2>mach_port_allocate</h2> <hr> <p> <strong>Function</strong> - Create caller-specified type of port right. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_allocate</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_right_t</strong> <var>right</var>, <strong>mach_port_name_t</strong> <var>*name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task acquiring the port right. <p> <dt> <var>right</var> <dd> [in scalar] The kind of entity to be created. This is one of the following: <dl> <p> <dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong> <dd> <strong>mach_port_allocate</strong> creates a port. The new port is not a member of any port set. It doesn't have any extant send or send-once rights. Its make-send count is zero, its sequence number is zero, its queue limit is <strong>MACH_PORT_QLIMIT_DEFAULT</strong>, and it has no queued messages. <var>name</var> denotes the receive right for the new port. <var>task</var> does not hold send rights for the new port, only the receive right. <strong>mach_port_insert_right</strong> and <strong>mach_port_extract_right</strong> can be used to convert the receive right into a combined send/receive right. <p> <dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong> <dd> <strong>mach_port_allocate</strong> creates a port set. The new port set has no members. <p> <dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong> <dd> <strong>mach_port_allocate</strong> creates a dead name. The new dead name has one user reference. </dl> <p> <dt> <var>name</var> <dd> [out scalar] The task's name for the port right. This can be any name that wasn't in use. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_allocate</strong> function creates a new right in the specified task. The new right's name is returned in name. <p> Ports that are allocated via this call do not support the full set of Mach port semantics; in particular, the kernel will not provide no-more-senders notification service requests on such ports. Any attempt to request no-more-senders notification service will generate an error. Use the <strong>mach_port_allocate_full</strong> interface to allocate ports that support the full set of Mach port semantics. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_NO_SPACE</strong> <dd> There was no room in task's IPC name space for another right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, <a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, <a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>, <a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>. \ No newline at end of file +<h2>mach_port_allocate</h2> +<hr> +<p> +<strong>Function</strong> - Create caller-specified type of port right. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_allocate</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_right_t</strong> <var>right</var>, + <strong>mach_port_name_t</strong> <var>*name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task acquiring the port right. +<p> +<dt> <var>right</var> +<dd> +[in scalar] +The kind of entity to be created. This is one of the following: +<dl> +<p> +<dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong> +<dd> +<strong>mach_port_allocate</strong> creates a port. The new port is not a +member of any port set. It doesn't have any extant send or +send-once rights. Its make-send count is zero, its sequence +number is zero, its queue limit is <strong>MACH_PORT_QLIMIT_DEFAULT</strong>, and +it has no queued messages. <var>name</var> denotes the +receive right for the new port. +<var>task</var> does not hold send rights for the new port, only the +receive right. <strong>mach_port_insert_right</strong> and +<strong>mach_port_extract_right</strong> can be used to convert the receive right into a +combined send/receive right. +<p> +<dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong> +<dd> +<strong>mach_port_allocate</strong> creates a port set. The new port set has +no members. +<p> +<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong> +<dd> +<strong>mach_port_allocate</strong> creates a dead name. The new dead +name has one user reference. +</dl> +<p> +<dt> <var>name</var> +<dd> +[out scalar] +The task's name for the port right. This can be any name +that wasn't in use. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_allocate</strong> function creates a new right +in the specified task. The new right's name is returned in name. +<p> +Ports that are allocated via this call do not support the full set of +Mach port semantics; in particular, the kernel will not provide no-more-senders +notification service requests on such ports. Any attempt to request no-more-senders +notification service +will generate an error. Use the <strong>mach_port_allocate_full</strong> +interface to allocate ports that support the full set of Mach port semantics. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_NO_SPACE</strong> +<dd> +There was no room in task's IPC name space for another right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, +<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, +<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>, +<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>. diff --git a/osfmk/man/mach_port_allocate_full.html b/osfmk/man/mach_port_allocate_full.html index 4cde74291..2363dfa0e 100755 --- a/osfmk/man/mach_port_allocate_full.html +++ b/osfmk/man/mach_port_allocate_full.html @@ -1 +1,96 @@ -<h2>mach_port_allocate_full</h2> <hr> <p> <strong>Function</strong> - Create a port right with full Mach port semantics. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_allocate_full</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_right_t</strong> <var>right</var>, <strong>subsystem_t</strong> <var>subsystem</var>, <strong>mach_port_qos_t</strong> <var>qos</var>, <strong>task</strong> <var>name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task acquiring the port right. <p> <dt> <var>right</var> <dd> [in scalar] The kind of entity to be created. This is one of the following: <dl> <p> <dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong> <dd> <strong>mach_port_allocate_full</strong> creates a port. The new port is not a member of any port set. It doesn't have any extant send or send-once rights. Its make-send count is zero, its sequence number is zero, its queue limit is MACH_PORT_QLIMIT_DEFAULT, and it has no queued messages. The <var>name</var> parameter denotes the receive right for the new port. The owning task does not hold send rights for the new port, only the receive right. The <strong>mach_port_insert_right</strong> and <strong>mach_port_extract_right</strong> interfaces can be used to convert the receive right to a combined send/receive right. <p> <dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong> <dd> <strong>mach_port_allocate_full</strong> creates a port set. The new port set has no members. <p> <dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong> <dd> <strong>mach_port_allocate_full</strong> creates a dead name. The new dead name has one user reference. </dl> <p> <dt> <var>subsystem</var> <dd> [in scalar] The port right naming the subsystem the newly created port is to be associated with. <p> <p> <dt> <var>qos</var> <dd> [pointer to an in/out structure] Structure used to specify the desired "quality of service." This structure may be used to mandate the name of the returned port right and/or the port's "quality of service" attribute. The current implementation recognizes two such attributes: regular and realtime. <dt> <var>name</var> <dd> [out scalar] The task's name for the port right. This can be any name that wasn't in use. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_allocate_full</strong> function creates a new right in the specified task. The new right's name is returned via the <var>name</var> parameter. The new port supports the full set of Mach port semantics (i.e. no_more_senders detection will work, if requested). <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_NO_SPACE</strong> <dd> There was no room in task's IPC name space for another right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, <a href="mach_port_allocate.html"><strong>mach_port_allocate_qos</strong></a>, <a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, <a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, <a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>, <a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>. <p> Structures: <a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>. \ No newline at end of file +<h2>mach_port_allocate_full</h2> +<hr> +<p> +<strong>Function</strong> - Create a port right with full Mach port semantics. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_allocate_full</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_right_t</strong> <var>right</var>, + <strong>subsystem_t</strong> <var>subsystem</var>, + <strong>mach_port_qos_t</strong> <var>qos</var>, + <strong>task</strong> <var>name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] The task acquiring the port right. +<p> +<dt> <var>right</var> +<dd> +[in scalar] The kind of entity to be created. This is one of the following: +<dl> +<p> +<dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong> +<dd> +<strong>mach_port_allocate_full</strong> creates a port. The new port is not a member +of any port set. It doesn't have any extant send or send-once +rights. Its make-send count is zero, its sequence number is zero, its +queue limit is MACH_PORT_QLIMIT_DEFAULT, and it has no queued +messages. The <var>name</var> parameter +denotes the receive right for the new port. +The owning task does not hold send rights for the new port, only the receive +right. The <strong>mach_port_insert_right</strong> +and <strong>mach_port_extract_right</strong> interfaces can be used +to convert the receive right to a combined send/receive right. +<p> +<dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong> +<dd> +<strong>mach_port_allocate_full</strong> creates a port set. The new port set +has no members. +<p> +<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong> +<dd> +<strong>mach_port_allocate_full</strong> creates a dead name. The new dead +name has one user reference. +</dl> +<p> +<dt> <var>subsystem</var> +<dd> +[in scalar] The port right naming the subsystem the newly created port +is to be associated with. +<p> +<p> +<dt> <var>qos</var> +<dd> +[pointer to an in/out structure] Structure used to specify +the desired "quality of service." This structure may be used +to mandate the name of the returned port right and/or the port's "quality +of service" attribute. The current implementation recognizes two such +attributes: regular and realtime. +<dt> <var>name</var> +<dd> +[out scalar] The task's name for the port right. This can be any name +that wasn't in use. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_allocate_full</strong> function creates a new right in the +specified task. The new right's name is returned via the <var>name</var> parameter. +The new port supports the full set of Mach port semantics (i.e. no_more_senders +detection will work, if requested). +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port +name parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_NO_SPACE</strong> +<dd> +There was no room in task's IPC name space for another right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, +<a href="mach_port_allocate.html"><strong>mach_port_allocate_qos</strong></a>, +<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, +<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, +<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>, +<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>. +<p> +Structures: +<a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>. diff --git a/osfmk/man/mach_port_allocate_name.html b/osfmk/man/mach_port_allocate_name.html index abdc831ec..6a2e8aba0 100755 --- a/osfmk/man/mach_port_allocate_name.html +++ b/osfmk/man/mach_port_allocate_name.html @@ -1 +1,79 @@ -<h2>mach_port_allocate_name</h2> <hr> <p> <strong>Function</strong> - Create a port right with the caller-specified name. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_allocate_name</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_right_t</strong> <var>right</var>, <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task acquiring the port right. <p> <dt> <var>right</var> <dd> [in scalar] The kind of entity to be created. This is one of the following: <dl> <p> <dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong> <dd> <strong>mach_port_allocate_name</strong> creates a port. The new port is not a member of any port set. It doesn't have any extant send or send-once rights. Its make-send count is zero, its sequence number is zero, its queue limit is <strong>MACH_PORT_QLIMIT_DEFAULT</strong>, and it has no queued messages. <var>name</var> denotes the receive right for the new port. <var>task</var> does not hold send rights for the new port, only the receive right. <strong>mach_port_insert_right</strong> and <strong>mach_port_extract_right</strong> can be used to convert the receive right into a combined send/receive right. <p> <dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong> <dd> <strong>mach_port_allocate_name</strong> creates a port set. The new port set has no members. <p> <dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong> <dd> <strong>mach_port_allocate_name</strong> creates a dead name. The new dead name has one user reference. </dl> <p> <dt> <var>name</var> <dd> [in scalar] The task's name for the port right. name must not already be in use for some right, and it can't be the reserved values <strong>MACH_PORT_NULL</strong> and <strong>MACH_PORT_DEAD</strong>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_allocate_name</strong> function creates a new right in the specified task, with a specified name for the new right. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_NAME_EXISTS</strong> <dd> name was already in use for a port right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, <a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, <a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>, <a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>. \ No newline at end of file +<h2>mach_port_allocate_name</h2> +<hr> +<p> +<strong>Function</strong> - Create a port right with the caller-specified name. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_allocate_name</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_right_t</strong> <var>right</var>, + <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task acquiring the port right. +<p> +<dt> <var>right</var> +<dd> +[in scalar] +The kind of entity to be created. This is one of the following: +<dl> +<p> +<dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong> +<dd> +<strong>mach_port_allocate_name</strong> creates a port. The new port is +not a member of any port set. It doesn't have any extant send +or send-once rights. Its make-send count is zero, its sequence +number is zero, its queue limit is <strong>MACH_PORT_QLIMIT_DEFAULT</strong>, +and it has no queued messages. +<var>name</var> denotes the receive right for the new port. +<var>task</var> does not hold send rights for the new port, only the +receive right. <strong>mach_port_insert_right</strong> and +<strong>mach_port_extract_right</strong> can be used to convert the receive right into a +combined send/receive right. +<p> +<dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong> +<dd> +<strong>mach_port_allocate_name</strong> creates a port set. The new port +set has no members. +<p> +<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong> +<dd> +<strong>mach_port_allocate_name</strong> creates a dead name. The new +dead name has one user reference. +</dl> +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The task's name for the port right. name must not already be +in use for some right, and it can't be the reserved values +<strong>MACH_PORT_NULL</strong> and <strong>MACH_PORT_DEAD</strong>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_allocate_name</strong> function creates a new +right in the specified +task, with a specified name for the new right. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_NAME_EXISTS</strong> +<dd> +name was already in use for a port right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, +<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, +<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>, +<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>. diff --git a/osfmk/man/mach_port_allocate_qos.html b/osfmk/man/mach_port_allocate_qos.html index 8887bf9fb..cfe43da82 100755 --- a/osfmk/man/mach_port_allocate_qos.html +++ b/osfmk/man/mach_port_allocate_qos.html @@ -1 +1,65 @@ -<h2>mach_port_allocate_qos</h2> <hr> <p> <strong>Function</strong> - Allocate a port with specified "quality of service." <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_allocate_qos</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_right_t</strong> <var>right</var>, <strong>mach_port_qos_t</strong> <var>qos</var>, <strong>mach_port_name_t*</strong> <var>name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>task</var> <dd> [in task send right] The task acquiring the port right to the allocated port. <dt> <var>right</var> <dd> [in scalar] The type of port right to map to the allocated port. <dt> <var>qos</var> <dd> [pointer to an in/out structure] Structure used to specify the desired "quality of service." This structure indicates whether or not the caller is providing a name for the port and whether or not the port will exhibit realtime behavior. <dt> <var>name</var> <dd> [in/out scalar] The name of the installed port right, either specified by the caller or chosen by the system. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_allocate_qos</strong> function allocates a port with caller-specified "quality of service" characteristics with or without a caller-specified name; in other words, the caller may specify a desired name or it may let the kernel generate the name. The new port is capable of supporting full Mach port semantics (i.e no-more-senders notification can be requested on the port). <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_NO_SPACE</strong> <dd> There was no room in task's IPC name space for another right. <dt> <strong>KERN_INVALID_VALUE</strong> <dd> The type of right specified by <var>right</var> is either invalid or conflicts with the requested "quality of service" as specified via <var>qos</var>. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, <a href="mach_port_allocate_full.html"><strong>mach_port_allocate_full</strong></a>, <a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, <a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, <a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>, <a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>. <p> Structures: <a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>. \ No newline at end of file +<h2>mach_port_allocate_qos</h2> +<hr> +<p> +<strong>Function</strong> - Allocate a port with specified "quality of service." +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_allocate_qos</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_right_t</strong> <var>right</var>, + <strong>mach_port_qos_t</strong> <var>qos</var>, + <strong>mach_port_name_t*</strong> <var>name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>task</var> +<dd> +[in task send right] The task acquiring the port right to the allocated port. +<dt> <var>right</var> +<dd> +[in scalar] The type of port right to map to the allocated port. +<dt> <var>qos</var> +<dd> +[pointer to an in/out structure] Structure used to specify +the desired "quality of service." This structure indicates whether + or not the caller is providing a name for the port and whether or not + the port will exhibit realtime behavior. +<dt> <var>name</var> +<dd> +[in/out scalar] The name of the installed port right, either specified by the + caller or chosen by the system. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_allocate_qos</strong> function allocates a port with +caller-specified "quality of service" characteristics with or without a +caller-specified name; in other words, the caller may specify a desired name +or it may let the kernel generate the name. The new port is capable of +supporting full Mach port semantics (i.e no-more-senders notification can be +requested on the port). +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port +name parameter. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>KERN_NO_SPACE</strong> +<dd> +There was no room in task's IPC name space for another right. +<dt> <strong>KERN_INVALID_VALUE</strong> +<dd> +The type of right specified by <var>right</var> is either invalid or conflicts +with the requested "quality of service" as specified via <var>qos</var>. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, +<a href="mach_port_allocate_full.html"><strong>mach_port_allocate_full</strong></a>, +<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, +<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, +<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>, +<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>. +<p> +Structures: +<a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>. \ No newline at end of file diff --git a/osfmk/man/mach_port_deallocate.html b/osfmk/man/mach_port_deallocate.html index 524e25a82..a03e4d874 100755 --- a/osfmk/man/mach_port_deallocate.html +++ b/osfmk/man/mach_port_deallocate.html @@ -1 +1,57 @@ -<h2>mach_port_deallocate</h2> <hr> <p> <strong>Function</strong> - Decrement the target port right's user reference count. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_deallocate</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task holding the right. <p> <dt> <var>name</var> <dd> [in scalar] The task's name for the right. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_deallocate</strong> function releases a user reference for a right. It is an alternate form of <strong>mach_port_mod_refs</strong> that allows a task to release a user reference for a send or send-once right without failing if the port has died and the right is now actually a dead name. <p> If <var>name</var> denotes a dead name, send right, or send-once right, then the right loses one user reference. If it only had one user reference, then the right is destroyed. If <var>name</var> does not denote an element in the port name space, the function returns success. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> The <var>name</var> parameter denoted an invalid right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, <a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, <a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>. \ No newline at end of file +<h2>mach_port_deallocate</h2> +<hr> +<p> +<strong>Function</strong> - Decrement the target port right's user reference count. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_deallocate</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task holding the right. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The task's name for the right. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_deallocate</strong> function releases a user reference +for a right. It is +an alternate form of <strong>mach_port_mod_refs</strong> that allows +a task to release a user +reference for a send or send-once right without failing if the +port has died and +the right is now actually a dead name. +<p> +If <var>name</var> denotes a dead name, send right, or send-once right, +then the right loses +one user reference. If it only had one user reference, then +the right is destroyed. +If <var>name</var> does not denote an element in the port name space, the +function returns +success. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +The <var>name</var> parameter denoted an invalid right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, +<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, +<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>. diff --git a/osfmk/man/mach_port_destroy.html b/osfmk/man/mach_port_destroy.html index 4a0a4ba0e..3981aec69 100755 --- a/osfmk/man/mach_port_destroy.html +++ b/osfmk/man/mach_port_destroy.html @@ -1 +1,71 @@ -<h2>mach_port_destroy</h2> <hr> <p> <strong>Function</strong> - Deallocate all port rights associated with specified name. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_destroy</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task holding the right. <p> <dt> <var>name</var> <dd> [in scalar] The task's name for the right. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_destroy</strong> function de-allocates all rights denoted by a name. The name becomes immediately available for reuse. <p> For most purposes, <strong>mach_port_mod_refs</strong> and <strong>mach_port_deallocate</strong> are preferable. <p> If <var>name</var> denotes a port set, then all members of the port set are implicitly removed from the port set. <p> If <var>name</var> denotes a receive right that is a member of a port set, the receive right is implicitly removed from the port set. Remaining messages queued to the port are destroyed and extant send and send-once rights turn into dead names. If those send and send-once rights have dead-name requests registered, then dead-name notifications are generated for them. <p> If <var>name</var> denotes a send-once right, then the destruction of the send-once right produces a send-once notification for the port. <p> If <var>name</var> denotes a send-once, send, and/or receive right, and it has a dead-name request registered, then a port-deleted notification is generated (as opposed to a dead-name notification). <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> The <var>name</var> parameter did not denote a right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, <a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, <a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>, <a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, <a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>. \ No newline at end of file +<h2>mach_port_destroy</h2> +<hr> +<p> +<strong>Function</strong> - Deallocate all port rights associated with specified name. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_destroy</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task holding the right. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The task's name for the right. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_destroy</strong> function de-allocates all rights +denoted by a name. +The name becomes immediately available for reuse. +<p> +For most purposes, +<strong>mach_port_mod_refs</strong> and <strong>mach_port_deallocate</strong> are +preferable. +<p> +If <var>name</var> denotes a port set, then all members of the port set are implicitly +removed from the port set. +<p> +If <var>name</var> denotes a receive right that is a member of a port set, +the receive right is +implicitly removed from the port set. Remaining messages queued to the port +are destroyed and extant send and send-once rights turn into dead names. If +those send and send-once rights have dead-name requests registered, then +dead-name notifications are generated for them. +<p> +If <var>name</var> denotes a send-once right, then +the destruction of the send-once right +produces a send-once notification for the port. +<p> +If <var>name</var> denotes a send-once, send, and/or receive right, and +it has a dead-name +request registered, then a port-deleted notification is generated +(as opposed to a +dead-name notification). +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +The <var>name</var> parameter did not denote a right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, +<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, +<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>, +<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, +<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>. diff --git a/osfmk/man/mach_port_extract_member.html b/osfmk/man/mach_port_extract_member.html index b23ef935a..a94c3bc6d 100755 --- a/osfmk/man/mach_port_extract_member.html +++ b/osfmk/man/mach_port_extract_member.html @@ -1 +1,89 @@ -<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]"> <title>mach_port_insert_member.html</title> </head> <body> <h2> mach_port_extract_member</h2> <hr> <p><b>Function</b> - Extract the specified receive right from the specified port set. <h3> SYNOPSIS</h3> <pre><b>kern_return_t mach_port_extract_member </b> <b>(ipc_space_t</b> <i>task</i>, <b>mach_port_name_t</b> <i>member</i>, <b>mach_port_name_t</b> set<b>);</b></pre> <h3> PARAMETERS</h3> <dl> <dt> <i>task</i></dt> <dd> [in task send right] The task holding the port set and receive right.</dd> <dt> <i>member</i></dt> <dd> [in scalar] The task's name for the receive right.</dd> <dt> <i>set</i></dt> <dd> [in scalar] The task's name for the port set.</dd> </dl> <h3> DESCRIPTION</h3> The <b>mach_port_extract_member</b> function removes a receive right from a port set. Any other port set memberships for the receive right are not affected. A receive right can be a member of any number of portsets simultaneously. <h3> NOTES</h3> This interface is machine word length specific because of the port name parameter. <h3> RETURN VALUES</h3> <dl> <dt> <b>KERN_INVALID_NAME</b></dt> <dd> <i>member</i> or <i>set</i> did not denote a right.</dd> <dt> <b>KERN_INVALID_RIGHT</b></dt> <dd> <i>member</i> denoted a right, but not a receive right, or <i>set</i> denoted a right, but not a port set.</dd> <dt> <b>KERN_NOT_IN_SET</b></dt> <dd> <i>member</i> was not in <i>set</i>.</dd> </dl> <h3> RELATED INFORMATION</h3> Functions: <b><a href="../HTML/mach_port_extract_member.html">mach_port_extract_member</a></b>, <b><a href="../HTML/mach_port_move_member.html">mach_port_move_member</a></b>, <b><a href="../HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>, <b><a href="../HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>. </body> </html> \ No newline at end of file +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]"> + <title>mach_port_insert_member.html</title> +</head> +<body> + +<h2> +mach_port_extract_member</h2> + +<hr> +<p><b>Function</b> - Extract the specified receive right from the specified +port set. +<h3> +SYNOPSIS</h3> + +<pre><b>kern_return_t mach_port_extract_member +</b> <b>(ipc_space_t</b> <i>task</i>, + <b>mach_port_name_t</b> <i>member</i>, + <b>mach_port_name_t</b> set<b>);</b></pre> + +<h3> +PARAMETERS</h3> + +<dl> +<dt> +<i>task</i></dt> + +<dd> +[in task send right] The task holding the port set and receive right.</dd> + +<dt> +<i>member</i></dt> + +<dd> +[in scalar] The task's name for the receive right.</dd> + +<dt> +<i>set</i></dt> + +<dd> +[in scalar] The task's name for the port set.</dd> +</dl> + +<h3> +DESCRIPTION</h3> +The <b>mach_port_extract_member</b> function removes a receive right from +a port set. Any other port set memberships for the receive right are not +affected. A receive right can be a member of any number of portsets +simultaneously. +<h3> +NOTES</h3> +This interface is machine word length specific because of the port name +parameter. +<h3> +RETURN VALUES</h3> + +<dl> +<dt> +<b>KERN_INVALID_NAME</b></dt> + +<dd> +<i>member</i> or <i>set</i> did not denote a right.</dd> + +<dt> +<b>KERN_INVALID_RIGHT</b></dt> + +<dd> +<i>member</i> denoted a right, but not a receive right, or <i>set</i> denoted +a right, but not a port set.</dd> + +<dt> +<b>KERN_NOT_IN_SET</b></dt> + +<dd> +<i>member</i> was not in <i>set</i>.</dd> +</dl> + +<h3> +RELATED INFORMATION</h3> +Functions: +<b><a href="../HTML/mach_port_extract_member.html">mach_port_extract_member</a></b>, +<b><a href="../HTML/mach_port_move_member.html">mach_port_move_member</a></b>, +<b><a href="../HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>, +<b><a href="../HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>. +</body> +</html> diff --git a/osfmk/man/mach_port_extract_right.html b/osfmk/man/mach_port_extract_right.html index 2bb9cd0aa..02e7b9247 100755 --- a/osfmk/man/mach_port_extract_right.html +++ b/osfmk/man/mach_port_extract_right.html @@ -1 +1,74 @@ -<h2>mach_port_extract_right</h2> <hr> <p> <strong>Function</strong> - Remove the specified right from the target task and return it to the caller. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_extract_right</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_msg_type_name_t</strong> <var>desired_type</var>, <strong>mach_port_poly_t</strong> <var>*right</var>, <strong>mach_msg_type_name_</strong> <var>*acquired_type</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task holding the port right. <p> <dt> <var>name</var> <dd> [in scalar] The task's name for the port right. <p> <dt> <var>desired_type</var> <dd> [in scalar] IPC type, specifying how the right should be extracted. <p> <dt> <var>right</var> <dd> [out random right] The extracted right. <p> <dt> <var>acquired_type</var> <dd> [out scalar] The type of the extracted right. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_extract_right</strong> function extracts a port right from the target task and returns it to the caller as if the task sent the right voluntarily, using <var>desired_type</var> as the disposition for the right. See <strong>mach_msg</strong>. <p> The returned value of <var>acquired_type</var> will be <strong>MACH_MSG_TYPE_PORT_SEND</strong> if a send right is extracted, <strong>MACH_MSG_TYPE_PORT_RECEIVE</strong> if a receive right is extracted, and <strong>MACH_MSG_TYPE_PORT_SEND_ONCE</strong> if a send-once right is extracted. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> <var>name</var> did not denote a right. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> <var>name</var> denoted an invalid right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>, <a href="mach_msg.html"><strong>mach_msg</strong></a>. \ No newline at end of file +<h2>mach_port_extract_right</h2> +<hr> +<p> +<strong>Function</strong> - Remove the specified right from the target task and return it to the caller. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_extract_right</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_msg_type_name_t</strong> <var>desired_type</var>, + <strong>mach_port_poly_t</strong> <var>*right</var>, + <strong>mach_msg_type_name_</strong> <var>*acquired_type</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task holding the port right. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The task's name for the port right. +<p> +<dt> <var>desired_type</var> +<dd> +[in scalar] +IPC type, specifying how the right should be extracted. +<p> +<dt> <var>right</var> +<dd> +[out random right] +The extracted right. +<p> +<dt> <var>acquired_type</var> +<dd> +[out scalar] +The type of the extracted right. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_extract_right</strong> function extracts a port +right from the target +task and returns it to the caller as if the task sent the right +voluntarily, using +<var>desired_type</var> as the disposition for the right. See <strong>mach_msg</strong>. +<p> +The returned value of <var>acquired_type</var> will be +<strong>MACH_MSG_TYPE_PORT_SEND</strong> if a send right is extracted, +<strong>MACH_MSG_TYPE_PORT_RECEIVE</strong> if a +receive right is extracted, and <strong>MACH_MSG_TYPE_PORT_SEND_ONCE</strong> if a +send-once right is extracted. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +<var>name</var> did not denote a right. +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +<var>name</var> denoted an invalid right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>, +<a href="mach_msg.html"><strong>mach_msg</strong></a>. diff --git a/osfmk/man/mach_port_get_attributes.html b/osfmk/man/mach_port_get_attributes.html index 4b115988b..f8cf730b2 100755 --- a/osfmk/man/mach_port_get_attributes.html +++ b/osfmk/man/mach_port_get_attributes.html @@ -1 +1,85 @@ -<h2>mach_port_get_attributes</h2> <hr> <p> <strong>Function</strong> - Return information about target port as specified by the caller. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_get_attributes</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_port_flavor_t</strong> <var>flavor</var>, <strong>mach_port_info_t</strong> <var>port_info</var>, <strong>mach_msg_type_number_t</strong> <var>*port_info_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task holding a receive right to the port in question. <p> <dt> <var>name</var> <dd> [in scalar] <var>task</var>'s name for the port. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of information to be returned. Valid values are: <dl> <p> <dt> <strong>MACH_PORT_LIMITS_INFO</strong> <dd> Returns the resource limits for the port. The declaration of this data is found in structure <strong>mach_port_limits</strong>. <p> <dt> <strong>MACH_PORT_RECEIVE_STATUS</strong> <dd> Returns random information about the rights and messages associated with the port. The declaration of this data is found in structure <strong>mach_port_status</strong>. </dl> <p> <dt> <var>port_info</var> <dd> [out structure] Information about the specified port. <p> <dt> <var>port_info_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_get_attributes</strong> function returns an information structure of type <var>flavor</var>. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter in the <strong>MACH_PORT_RECEIVE_STATUS</strong> structure return. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> <var>name</var> did not denote a right. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> <var>name</var> denoted a right, but not a receive right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, <a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, <a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>. <p> Data Structures: <a href="mach_port_limits.html"><strong>mach_port_limits</strong></a>, <a href="mach_port_status.html"><strong>mach_port_status</strong></a>. \ No newline at end of file +<h2>mach_port_get_attributes</h2> +<hr> +<p> +<strong>Function</strong> - Return information about target port as specified by the caller. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_get_attributes</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_port_flavor_t</strong> <var>flavor</var>, + <strong>mach_port_info_t</strong> <var>port_info</var>, + <strong>mach_msg_type_number_t</strong> <var>*port_info_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task holding a receive right to the port in +question. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +<var>task</var>'s name for the port. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of information to be returned. Valid values are: +<dl> +<p> +<dt> <strong>MACH_PORT_LIMITS_INFO</strong> +<dd> +Returns the resource limits for the port. The declaration of +this data is found in structure <strong>mach_port_limits</strong>. +<p> +<dt> <strong>MACH_PORT_RECEIVE_STATUS</strong> +<dd> +Returns random information about the rights and messages +associated with the port. The declaration of this data is found in +structure <strong>mach_port_status</strong>. +</dl> +<p> +<dt> <var>port_info</var> +<dd> +[out structure] +Information about the specified port. +<p> +<dt> <var>port_info_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_get_attributes</strong> function returns an information +structure of type <var>flavor</var>. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter in the <strong>MACH_PORT_RECEIVE_STATUS</strong> structure return. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +<var>name</var> did not denote a right. +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +<var>name</var> denoted a right, but not a receive right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, +<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, +<a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>. +<p> +Data Structures: +<a href="mach_port_limits.html"><strong>mach_port_limits</strong></a>, +<a href="mach_port_status.html"><strong>mach_port_status</strong></a>. diff --git a/osfmk/man/mach_port_get_refs.html b/osfmk/man/mach_port_get_refs.html index 8768383fe..a4bd96493 100755 --- a/osfmk/man/mach_port_get_refs.html +++ b/osfmk/man/mach_port_get_refs.html @@ -1 +1,78 @@ -<h2>mach_port_get_refs</h2> <hr> <p> <strong>Function</strong> - Return the current count of user references on the target port right. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_get_refs</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_port_right_t</strong> <var>right</var>, <strong>mach_port_urefs_t</strong> <var>*refs</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task holding the right. <p> <dt> <var>name</var> <dd> [in scalar] The task's name for the right. <p> <dt> <var>right</var> <dd> [in scalar] The type of right/entity being examined: <dl> <p> <dt> <dd> <strong>MACH_PORT_RIGHT_SEND</strong> <p> <dt> <dd> <strong>MACH_PORT_RIGHT_RECEIVE</strong> <p> <dt> <dd> <strong>MACH_PORT_RIGHT_SEND_ONCE</strong> <p> <dt> <dd> <strong>MACH_PORT_RIGHT_PORT_SET</strong> <p> <dt> <dd> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong> </dl> <p> <dt> <var>refs</var> <dd> [out scalar] Number of user references. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_get_refs</strong> function returns the number of user references a task has for a right. <p> If <var>name</var> denotes a right, but not the type of right specified, then zero is returned. Otherwise a positive number of user references is returned. Note a name may simultaneously denote send and receive rights. The number of references for send-once rights is always one. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> <var>name</var> did not denote a right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>. \ No newline at end of file +<h2>mach_port_get_refs</h2> +<hr> +<p> +<strong>Function</strong> - Return the current count of user references on the target port right. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_get_refs</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_port_right_t</strong> <var>right</var>, + <strong>mach_port_urefs_t</strong> <var>*refs</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task holding the right. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The task's name for the right. +<p> +<dt> <var>right</var> +<dd> +[in scalar] +The type of right/entity being examined: +<dl> +<p> +<dt> <dd> +<strong>MACH_PORT_RIGHT_SEND</strong> +<p> +<dt> <dd> +<strong>MACH_PORT_RIGHT_RECEIVE</strong> +<p> +<dt> <dd> +<strong>MACH_PORT_RIGHT_SEND_ONCE</strong> +<p> +<dt> <dd> +<strong>MACH_PORT_RIGHT_PORT_SET</strong> +<p> +<dt> <dd> +<strong>MACH_PORT_RIGHT_DEAD_NAME</strong> +</dl> +<p> +<dt> <var>refs</var> +<dd> +[out scalar] +Number of user references. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_get_refs</strong> function returns the number +of user references a task +has for a right. +<p> +If <var>name</var> denotes a right, but not the type of right specified, +then zero is returned. +Otherwise a positive number of user references is returned. Note a name may +simultaneously denote send and receive rights. The number of references for +send-once rights is always one. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +<var>name</var> did not denote a right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>. diff --git a/osfmk/man/mach_port_get_set_status.html b/osfmk/man/mach_port_get_set_status.html index 3860a761c..b5f9a289c 100755 --- a/osfmk/man/mach_port_get_set_status.html +++ b/osfmk/man/mach_port_get_set_status.html @@ -1 +1,71 @@ -<h2>mach_port_get_set_status</h2> <hr> <p> <strong>Function</strong> - Return the port right names contained in the target port set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_get_set_status</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_port_name_array_t</strong> <var>*members</var>, <strong>task</strong> <var>count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task holding the port set. <p> <dt> <var>name</var> <dd> [in scalar] The task's name for the port set. <p> <dt> <var>members</var> <dd> [out pointer to dynamic array of <var>mach_port_name_t</var>] The task's names for the port set's members. <p> <dt> <var>count</var> <dd> [out scalar] The number of member names returned. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_get_set_status</strong> function returns the individual port right names for all port rights contained in the specified port set. The <var>members</var> parameter is an array that is automatically allocated when the reply message is received. Note that <strong>vm_deallocate</strong> should be used to free the array. <p> Note that this interface, unlike others such as <strong>task_threads</strong>, returns a collection of port right names, NOT a collection of port rights themselves. In other words, this function does not insert port rights into the caller's port right name space; consequently, a call to <strong>mach_port_get_set_status</strong> does not affect the reference count of each port right within the target port set. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter and the returned port names. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> <var>name</var> did not denote a right. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> <var>name</var> denoted a right, but not a port set. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_insert_member.html"><strong>mach_port_insert_member</strong></a>, <a href="mach_port_extract_member.html"><strong>mach_port_extract_member</strong></a>, <a href="mach_port_move_member.html"><strong>mach_port_move_member</strong></a>, <a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>. \ No newline at end of file +<h2>mach_port_get_set_status</h2> +<hr> +<p> +<strong>Function</strong> - Return the port right names contained in the target port set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_get_set_status</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_port_name_array_t</strong> <var>*members</var>, + <strong>task</strong> <var>count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task holding the port set. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The task's name for the port set. +<p> +<dt> <var>members</var> +<dd> +[out pointer to dynamic array of <var>mach_port_name_t</var>] +The task's names +for the port set's members. +<p> +<dt> <var>count</var> +<dd> +[out scalar] +The number of member names returned. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_get_set_status</strong> function returns the individual port +right names for all port rights contained in the specified port set. +The <var>members</var> parameter is an array that is automatically +allocated when the reply message is received. Note that +<strong>vm_deallocate</strong> should be used to free the array. +<p> +Note that this interface, unlike others such as <strong>task_threads</strong>, +returns a collection of port right names, NOT a collection of port rights themselves. +In other words, this function does not insert port rights into the caller's +port right name space; consequently, a call to <strong>mach_port_get_set_status</strong> +does not affect the reference count of each port right within the target port set. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter and the returned port names. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +<var>name</var> did not denote a right. +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +<var>name</var> denoted a right, but not a port set. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_insert_member.html"><strong>mach_port_insert_member</strong></a>, +<a href="mach_port_extract_member.html"><strong>mach_port_extract_member</strong></a>, +<a href="mach_port_move_member.html"><strong>mach_port_move_member</strong></a>, +<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>. diff --git a/osfmk/man/mach_port_insert_member.html b/osfmk/man/mach_port_insert_member.html index 76cf957d3..f57cdc051 100755 --- a/osfmk/man/mach_port_insert_member.html +++ b/osfmk/man/mach_port_insert_member.html @@ -1 +1,83 @@ -<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]"> <title>mach_port_insert_member.html</title> </head> <body> <h2> mach_port_insert_member</h2> <hr> <p><b>Function</b> - Move the specified receive right into or out of the specified port set. <h3> SYNOPSIS</h3> <pre><b>kern_return_t mach_port_insert_member </b> <b>(ipc_space_t</b> <i>task</i>, <b>mach_port_name_t</b> <i>member</i>, <b>mach_port_name_t</b> <i>set</i><b>);</b></pre> <h3> PARAMETERS</h3> <dl> <dt> <i>task</i></dt> <dd> [in task send right] The task holding the port set and receive right.</dd> <dt> <i>member</i></dt> <dd> [in scalar] The task's name for the receive right.</dd> <dt> <i>set</i></dt> <dd> [in scalar] The task's name for the port set.</dd> </dl> <h3> DESCRIPTION</h3> The <b>mach_port_insert_member</b> function adds a receive right to a port set. If the receive right is already a member of another port set, that relationship is unafected by this operation. A receive right can be in multiple port sets simultaneously. <h3> NOTES</h3> This interface is machine word length specific because of the port name parameter. <h3> RETURN VALUES</h3> <dl> <dt> <b>KERN_INVALID_NAME</b></dt> <dd> <i>member</i> or <i>set</i> did not denote a right.</dd> <dt> <b>KERN_INVALID_RIGHT</b></dt> <dd> <i>member</i> denoted a right, but not a receive right, or <i>set</i> denoted a right, but not a port set.</dd> </dl> <h3> RELATED INFORMATION</h3> Functions: <b><a href="HTML/mach_port_extract_member.html">mach_port_extract_member</a></b>, <b><a href="HTML/mach_port_move_member.html">mach_port_move_member</a></b>, <b><a href="HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>, <b><a href="HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>. </body> </html> \ No newline at end of file +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]"> + <title>mach_port_insert_member.html</title> +</head> +<body> + +<h2> +mach_port_insert_member</h2> + +<hr> +<p><b>Function</b> - Move the specified receive right into or out of the +specified port set. +<h3> +SYNOPSIS</h3> + +<pre><b>kern_return_t mach_port_insert_member +</b> <b>(ipc_space_t</b> <i>task</i>, + <b>mach_port_name_t</b> <i>member</i>, + <b>mach_port_name_t</b> <i>set</i><b>);</b></pre> + +<h3> +PARAMETERS</h3> + +<dl> +<dt> +<i>task</i></dt> + +<dd> +[in task send right] The task holding the port set and receive right.</dd> + +<dt> +<i>member</i></dt> + +<dd> +[in scalar] The task's name for the receive right.</dd> + +<dt> +<i>set</i></dt> + +<dd> +[in scalar] The task's name for the port set.</dd> +</dl> + +<h3> +DESCRIPTION</h3> +The <b>mach_port_insert_member</b> function adds a receive right to a port +set. If the receive right is already a member of another port set, that +relationship is unafected by this operation. A receive right can +be in multiple port sets simultaneously. +<h3> +NOTES</h3> +This interface is machine word length specific because of the port name +parameter. +<h3> +RETURN VALUES</h3> + +<dl> +<dt> +<b>KERN_INVALID_NAME</b></dt> + +<dd> +<i>member</i> or <i>set</i> did not denote a right.</dd> + +<dt> +<b>KERN_INVALID_RIGHT</b></dt> + +<dd> +<i>member</i> denoted a right, but not a receive right, or <i>set</i> denoted +a right, but not a port set.</dd> +</dl> + +<h3> +RELATED INFORMATION</h3> +Functions: +<b><a href="HTML/mach_port_extract_member.html">mach_port_extract_member</a></b>, +<b><a href="HTML/mach_port_move_member.html">mach_port_move_member</a></b>, +<b><a href="HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>, +<b><a href="HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>. +</body> +</html> diff --git a/osfmk/man/mach_port_insert_right.html b/osfmk/man/mach_port_insert_right.html index 3cda5863e..7e6cd6262 100755 --- a/osfmk/man/mach_port_insert_right.html +++ b/osfmk/man/mach_port_insert_right.html @@ -1 +1,101 @@ -<h2>mach_port_insert_right</h2> <hr> <p> <strong>Function</strong> - Insert the specified port right into the target task. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_insert_right</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_port_poly_t</strong> <var>right</var>, <strong>mach_msg_type_name_t</strong> <var>right_type</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task which gets the caller's right. <p> <dt> <var>name</var> <dd> [in scalar] The name by which <var>task</var> will know the right. <p> <dt> <var>right</var> <dd> [in random right] The port right. <p> <dt> <var>right_type</var> <dd> [in scalar] IPC type of the sent right; e.g., <strong>MACH_MSG_TYPE_COPY_SEND</strong> or <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_insert_right</strong> function inserts into <var>task</var> the caller's right for a port, using a specified name for the right in the target task. <p> The specified <var>name</var> can't be one of the reserved values <strong>MACH_PORT_NULL</strong> or <strong>MACH_PORT_DEAD</strong>. The <var>right</var> can't be <strong>MACH_PORT_NULL</strong> or <strong>MACH_PORT_DEAD</strong>. <p> The argument <var>right_type</var> specifies a right to be inserted and how that right should be extracted from the caller. It should be a value appropriate for <strong>mach_msg</strong>. <p> If <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>, or <strong>MACH_MSG_TYPE_COPY_SEND</strong>, then a send right is inserted. If the target already holds send or receive rights for the port, then <var>name</var> should denote those rights in the target. Otherwise, <var>name</var> should be unused in the target. If the target already has send rights, then those send rights gain an additional user reference. Otherwise, the target gains a send right, with a user reference count of one. <p> If <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or <strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>, then a send-once right is inserted. The <var>name</var> should be unused in the target. The target gains a send-once right. <p> If <var>right_type</var> is <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>, then a receive right is inserted. If the target already holds send rights for the port, then <var>name</var> should denote those rights in the target. Otherwise, <var>name</var> should be unused in the target. The receive right is moved into the target task. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_NAME_EXISTS</strong> <dd> <var>name</var> already denoted a right. <p> <dt> <strong>KERN_INVALID_CAPABILITY</strong> <dd> <var>right</var> was null or dead. <p> <dt> <strong>KERN_UREFS_OVERFLOW</strong> <dd> Inserting the right would overflow <var>name</var>'s user-reference count. <p> <dt> <strong>KERN_RIGHT_EXISTS</strong> <dd> <var>task</var> already had rights for the port, with a different name. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>, <a href="mach_msg.html"><strong>mach_msg</strong></a>. \ No newline at end of file +<h2>mach_port_insert_right</h2> +<hr> +<p> +<strong>Function</strong> - Insert the specified port right into the target task. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_insert_right</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_port_poly_t</strong> <var>right</var>, + <strong>mach_msg_type_name_t</strong> <var>right_type</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task which gets the caller's right. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The name by which <var>task</var> will know the right. +<p> +<dt> <var>right</var> +<dd> +[in random right] +The port right. +<p> +<dt> <var>right_type</var> +<dd> +[in scalar] +IPC type of the sent right; e.g., +<strong>MACH_MSG_TYPE_COPY_SEND</strong> or <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_insert_right</strong> function inserts into <var>task</var> +the caller's right for a +port, using a specified name for the right in the target task. +<p> +The specified <var>name</var> can't be one of the reserved values <strong>MACH_PORT_NULL</strong> +or <strong>MACH_PORT_DEAD</strong>. The <var>right</var> can't be <strong>MACH_PORT_NULL</strong> or +<strong>MACH_PORT_DEAD</strong>. +<p> +The argument <var>right_type</var> specifies a right to be inserted and how that right +should be extracted from the caller. It should be a value appropriate for +<strong>mach_msg</strong>. +<p> +If <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>, +or +<strong>MACH_MSG_TYPE_COPY_SEND</strong>, then a send right is inserted. If the target +already holds send or receive rights for the port, then <var>name</var> +should denote those rights in the target. Otherwise, <var>name</var> should +be unused in +the target. If the target already has send rights, then those +send rights gain an +additional user reference. Otherwise, the target gains a send +right, with a user +reference count of one. +<p> +If <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or +<strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>, then a send-once right is inserted. +The <var>name</var> should be unused in the target. The +target gains a send-once right. +<p> +If <var>right_type</var> is <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>, then a receive right is +inserted. If the target already holds send rights for the port, +then <var>name</var> should +denote those rights in the target. Otherwise, <var>name</var> should be +unused in the target. +The receive right is moved into the target task. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_NAME_EXISTS</strong> +<dd> +<var>name</var> already denoted a right. +<p> +<dt> <strong>KERN_INVALID_CAPABILITY</strong> +<dd> +<var>right</var> was null or dead. +<p> +<dt> <strong>KERN_UREFS_OVERFLOW</strong> +<dd> +Inserting the right would overflow <var>name</var>'s user-reference count. +<p> +<dt> <strong>KERN_RIGHT_EXISTS</strong> +<dd> +<var>task</var> already had rights for the port, with a different name. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>, +<a href="mach_msg.html"><strong>mach_msg</strong></a>. diff --git a/osfmk/man/mach_port_limits.html b/osfmk/man/mach_port_limits.html index 1c2b811eb..d7ecb035c 100755 --- a/osfmk/man/mach_port_limits.html +++ b/osfmk/man/mach_port_limits.html @@ -1 +1,34 @@ -<h2>mach_port_limits</h2> <hr> <p> <strong>Structure</strong> - Specifies a port's resource and message queue limits. <h3>SYNOPSIS</h3> <pre> <strong>struct mach_port_limits</strong> <strong>{</strong> <strong>mach_port_msgcount_t</strong> <var>queue_limit</var><strong>;</strong> <strong>};</strong> <strong>typedef struct mach_port_limits* mach_port_limits_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>queue_limit</var> <dd> Number of messages allowed to be on the message queue at any given time. Attempts to queue more messages than this limit will block. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_limits</strong> structure defines various limits governing the messages that can be sent through the port. (In the current implementation, the structure maintains only a queue length limit.) <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>, <a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>. <p> Structures: <a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>. \ No newline at end of file +<h2>mach_port_limits</h2> +<hr> +<p> +<strong>Structure</strong> - Specifies a port's resource and message queue limits. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct mach_port_limits</strong> +<strong>{</strong> + <strong>mach_port_msgcount_t</strong> <var>queue_limit</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct mach_port_limits* mach_port_limits_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>queue_limit</var> +<dd> +Number of messages allowed to be on the message queue at any given +time. Attempts to queue more messages than this limit will block. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_limits</strong> structure defines various limits +governing the messages that can be sent through the port. (In the current +implementation, the structure maintains only a queue length limit.) +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>, +<a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>. +<p> +Structures: +<a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>. + diff --git a/osfmk/man/mach_port_mod_refs.html b/osfmk/man/mach_port_mod_refs.html index 9ec947f45..f1606af31 100755 --- a/osfmk/man/mach_port_mod_refs.html +++ b/osfmk/man/mach_port_mod_refs.html @@ -1 +1,108 @@ -<h2>mach_port_mod_refs</h2> <hr> <p> <strong>Function</strong> - Modify the specified port right's count of user references. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_mod_refs</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_port_right_t</strong> <var>right</var>, <strong>mach_port_delta_t</strong> <var>delta</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task holding the right. <p> <dt> <var>name</var> <dd> [in scalar] The task's name for the right. <p> <dt> <var>right</var> <dd> [in scalar] The type of right/entity being modified: <dl> <p> <dt> <strong>MACH_PORT_RIGHT_SEND</strong> <p> <dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong> <p> <dt> <strong>MACH_PORT_RIGHT_SEND_ONCE</strong> <p> <dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong> <p> <dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong> </dl> <p> <dt> <var>delta</var> <dd> [in scalar] Signed change to the number of user references. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_mod_refs</strong> function requests that the number of user references a task has for a right be changed. This results in the right being destroyed, if the number of user references is changed to zero. <p> The <var>name</var> parameter should denote the specified right. The number of user references for the right is changed by the amount <var>delta</var>, subject to the following restrictions: port sets, receive rights, and send-once rights may only have one user reference. The resulting number of user references can't be negative. If the resulting number of user references is zero, the effect is to de-allocate the right. For dead names and send rights, there is an implementation-defined maximum number of user references. <p> If the call destroys the right, then the effect is as described for <strong>mach_port_destroy</strong>, with the exception that <strong>mach_port_destroy</strong> simultaneously destroys all the rights denoted by a name, while <strong>mach_port_mod_refs</strong> can only destroy one right. The name will be available for reuse if it only denoted the one right. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> <var>name</var> did not denote a right. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> <var>name</var> denoted a right, but not the specified right. <p> <dt> <strong>KERN_INVALID_VALUE</strong> <dd> The user-reference count would become negative. <p> <dt> <strong>KERN_UREFS_OVERFLOW</strong> <dd> The user-reference count would overflow. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_destroy.html"><strong>mach_port_destroy</strong></a>, <a href="mach_port_get_refs.html"><strong>mach_port_get_refs</strong></a>. \ No newline at end of file +<h2>mach_port_mod_refs</h2> +<hr> +<p> +<strong>Function</strong> - Modify the specified port right's count of user references. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_mod_refs</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_port_right_t</strong> <var>right</var>, + <strong>mach_port_delta_t</strong> <var>delta</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task holding the right. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The task's name for the right. +<p> +<dt> <var>right</var> +<dd> +[in scalar] +The type of right/entity being modified: +<dl> +<p> +<dt> +<strong>MACH_PORT_RIGHT_SEND</strong> +<p> +<dt> +<strong>MACH_PORT_RIGHT_RECEIVE</strong> +<p> +<dt> +<strong>MACH_PORT_RIGHT_SEND_ONCE</strong> +<p> +<dt> +<strong>MACH_PORT_RIGHT_PORT_SET</strong> +<p> +<dt> +<strong>MACH_PORT_RIGHT_DEAD_NAME</strong> +</dl> +<p> +<dt> <var>delta</var> +<dd> +[in scalar] +Signed change to the number of user references. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_mod_refs</strong> function requests that the number +of user references a task has for a right be changed. This results +in the right +being destroyed, if the +number of user references is changed to zero. +<p> +The <var>name</var> parameter +should denote the specified right. The number of user references for +the right is changed by the amount <var>delta</var>, subject to the following +restrictions: +port sets, receive rights, and send-once rights may only have +one user reference. +The resulting number of user references can't be negative. If the resulting +number of user references is zero, the effect is to de-allocate +the right. For dead +names and send rights, there is an implementation-defined maximum number of +user references. +<p> +If the call destroys the right, then the effect is as described for +<strong>mach_port_destroy</strong>, with the exception that +<strong>mach_port_destroy</strong> +simultaneously destroys all +the rights denoted by a name, while <strong>mach_port_mod_refs</strong> +can only destroy +one right. The name will be available for reuse if it only denoted +the one right. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +<var>name</var> did not denote a right. +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +<var>name</var> denoted a right, but not the specified right. +<p> +<dt> <strong>KERN_INVALID_VALUE</strong> +<dd> +The user-reference count would become negative. +<p> +<dt> <strong>KERN_UREFS_OVERFLOW</strong> +<dd> +The user-reference count would overflow. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_destroy.html"><strong>mach_port_destroy</strong></a>, +<a href="mach_port_get_refs.html"><strong>mach_port_get_refs</strong></a>. diff --git a/osfmk/man/mach_port_move_member.html b/osfmk/man/mach_port_move_member.html index c21248329..2429a8632 100755 --- a/osfmk/man/mach_port_move_member.html +++ b/osfmk/man/mach_port_move_member.html @@ -1 +1,95 @@ -<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]"> <title>mach_port_insert_member.html</title> </head> <body> <h2> mach_port_move_member</h2> <hr> <p><b>Function</b> - Move the specified receive right into or out of the specified port set. <h3> SYNOPSIS</h3> <pre><b>kern_return_t mach_port_move_member </b> <b>(ipc_space_t</b> <i>task</i>, <b>mach_port_name_t</b> <i>member</i>, <b>mach_port_name_t</b> <i>after</i><b>);</b></pre> <h3> PARAMETERS</h3> <dl> <dt> <i>task</i></dt> <dd> [in task send right] The task holding the port set and receive right.</dd> <dt> <i>member</i></dt> <dd> [in scalar] The task's name for the receive right.</dd> <dt> <i>after</i></dt> <dd> [in scalar] The task's name for the port set.</dd> </dl> <h3> DESCRIPTION</h3> The <b>mach_port_move_member</b> function moves a receive right into a port set. If the receive right is already a member of any other port sets, it is removed from those sets first. If the port set is <b>MACH_PORT_NULL</b>, then the receive right is not put into a port set, but removed from all its current port sets. <h3> NOTES</h3> This interface is machine word length specific because of the port name parameter. <h3> RETURN VALUES</h3> <dl> <dt> <b>KERN_INVALID_NAME</b></dt> <dd> <i>member</i> or <i>after</i> did not denote a right.</dd> <dt> <b>KERN_INVALID_RIGHT</b></dt> <dd> <i>member</i> denoted a right, but not a receive right, or <i>after</i> denoted a right, but not a port set.</dd> <dt> <b>KERN_NOT_IN_SET</b></dt> <dd> <i>after</i> was <b>MACH_PORT_NULL</b>, but <i>member</i> wasn't currently in a port set.</dd> </dl> <h3> RELATED INFORMATION</h3> <p> Functions: <b><a href="../HTML/mach_port_insert_member.html">mach_port_insert_member</a></b>, <b><a href="../HTML/mach_port_extract_member.html">mach_port_extract_member</b></a>, <b><a href="../HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>, <b><a href="../HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>. </p> </body> </html> \ No newline at end of file +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]"> + <title>mach_port_insert_member.html</title> +</head> +<body> + +<h2> +mach_port_move_member</h2> + +<hr> +<p><b>Function</b> - Move the specified receive right into or out of the +specified port set. +<h3> +SYNOPSIS</h3> + +<pre><b>kern_return_t mach_port_move_member +</b> <b>(ipc_space_t</b> <i>task</i>, + <b>mach_port_name_t</b> <i>member</i>, + <b>mach_port_name_t</b> <i>after</i><b>);</b></pre> + +<h3> +PARAMETERS</h3> + +<dl> +<dt> +<i>task</i></dt> + +<dd> +[in task send right] The task holding the port set and receive right.</dd> + +<dt> +<i>member</i></dt> + +<dd> +[in scalar] The task's name for the receive right.</dd> + +<dt> +<i>after</i></dt> + +<dd> +[in scalar] The task's name for the port set.</dd> +</dl> + +<h3> +DESCRIPTION</h3> +The <b>mach_port_move_member</b> function moves a receive right into a +port set. If the receive right is already a member of any other port sets, +it is removed from those sets first. If the port set is <b>MACH_PORT_NULL</b>, +then the receive right is not put into a port set, but removed from all +its current port sets. +<h3> +NOTES</h3> +This interface is machine word length specific because of the port name +parameter. +<h3> +RETURN VALUES</h3> + +<dl> +<dt> +<b>KERN_INVALID_NAME</b></dt> + +<dd> +<i>member</i> or <i>after</i> did not denote a right.</dd> + +<dt> +<b>KERN_INVALID_RIGHT</b></dt> + +<dd> +<i>member</i> denoted a right, but not a receive right, or <i>after</i> +denoted a right, but not a port set.</dd> + +<dt> +<b>KERN_NOT_IN_SET</b></dt> + +<dd> +<i>after</i> was <b>MACH_PORT_NULL</b>, but <i>member</i> wasn't currently +in a port set.</dd> +</dl> + +<h3> +RELATED INFORMATION</h3> + +<p> +Functions: +<b><a href="../HTML/mach_port_insert_member.html">mach_port_insert_member</a></b>, +<b><a href="../HTML/mach_port_extract_member.html">mach_port_extract_member</b></a>, +<b><a href="../HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>, +<b><a href="../HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>. +</p> + +</body> +</html> diff --git a/osfmk/man/mach_port_names.html b/osfmk/man/mach_port_names.html index daf43359a..2739ccbfe 100755 --- a/osfmk/man/mach_port_names.html +++ b/osfmk/man/mach_port_names.html @@ -1 +1,70 @@ -<h2>mach_port_names</h2> <hr> <p> <strong>Function</strong> - Return information about a task's port name space. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_names</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_array_t</strong> <var>*names</var>, <strong>mach_msg_type_number_t</strong> <var>*namesCnt</var>, <strong>mach_port_type_array_</strong> <var>*types</var>, <strong>mach_msg_type_number_t</strong> <var>*typesCnt</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task whose port name space is queried. <p> <dt> <var>names</var> <dd> [out pointer to dynamic array of <var>mach_port_name_t</var>] The names of the ports, port sets, and dead names in the task's port name space, in no particular order. <p> <dt> <var>namesCnt</var> <dd> [out scalar] The number of names returned. <p> <dt> <var>types</var> <dd> [out pointer to dynamic array of <var>mach_port_type_t</var>] The type of each corresponding name. Indicates what kind of rights the task holds with that name. <p> <dt> <var>typesCnt</var> <dd> [out scalar] The number of types returned. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_names</strong> returns information about <var>task</var>'s port name space. It returns task's currently active names, which represent some port, port set, or dead name right. For each name, it also returns what type of rights <var>task</var> holds (the same information returned by <strong>mach_port_type</strong>). <p> Note that when a call to <strong>mach_port_names</strong> returns, the number of entries in the two output arrays (<var>names</var> and <var>types</var>) are equal (<var>namesCnt</var> equals <var>typesCnt</var>). The fact that this interface returns two separate counts is an artifact of the Mach Interface Generator. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter and the returned port names. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_type.html"><strong>mach_port_type</strong></a>. \ No newline at end of file +<h2>mach_port_names</h2> +<hr> +<p> +<strong>Function</strong> - Return information about a task's port name space. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_names</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_array_t</strong> <var>*names</var>, + <strong>mach_msg_type_number_t</strong> <var>*namesCnt</var>, + <strong>mach_port_type_array_</strong> <var>*types</var>, + <strong>mach_msg_type_number_t</strong> <var>*typesCnt</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task whose port name space is queried. +<p> +<dt> <var>names</var> +<dd> +[out pointer to dynamic array of <var>mach_port_name_t</var>] +The names of the +ports, port sets, and dead names in the task's port name space, in no +particular order. +<p> +<dt> <var>namesCnt</var> +<dd> +[out scalar] +The number of names returned. +<p> +<dt> <var>types</var> +<dd> +[out pointer to dynamic array of <var>mach_port_type_t</var>] +The type of each +corresponding name. Indicates what kind of rights the task holds with +that name. +<p> +<dt> <var>typesCnt</var> +<dd> +[out scalar] +The number of types returned. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_names</strong> returns information about <var>task</var>'s +port name space. It +returns task's currently active names, which represent some port, +port set, or dead +name right. For each name, it also returns what type of rights +<var>task</var> holds (the +same information returned by <strong>mach_port_type</strong>). +<p> +Note that when a call to <strong>mach_port_names</strong> returns, the +number of entries in the two output arrays (<var>names</var> and <var>types</var>) +are equal (<var>namesCnt</var> equals <var>typesCnt</var>). The fact that this +interface returns two separate counts is an artifact of the Mach Interface Generator. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter and the returned port names. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_type.html"><strong>mach_port_type</strong></a>. diff --git a/osfmk/man/mach_port_qos.html b/osfmk/man/mach_port_qos.html index 3011ab78a..fd952bda8 100755 --- a/osfmk/man/mach_port_qos.html +++ b/osfmk/man/mach_port_qos.html @@ -1 +1,46 @@ -<h2>mach_port_qos</h2> <hr> <p> <strong>Structure</strong> - Specifies a port's attributes with respect to "Quality Of Service." <h3>SYNOPSIS</h3> <pre> <strong>typedef struct mach_port_qos</strong> <strong>{</strong> <strong>boolean_t</strong> <var>name</var><strong>;</strong> <strong>boolean_t</strong> <var>rt</var><strong>;</strong> <strong>boolean_t</strong> <var>pad1</var><strong>;</strong> <strong>boolean_t</strong> <var>pad2</var><strong>;</strong> <strong>} mach_port_qos_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>name</var> <dd> If TRUE, the system will bestow the user-specified name on the newly allocated port. Otherwise, the system will choose the port's name. <p> <dt> <var>rt</var> <dd> If TRUE, this field causes a realtime port to be allocated. Otherwise, a regular port will be allocated. <p> <dt> <var>pad1</var> <dd> A 30 bit padding field. <p> <dt> <var>pad2</var> <dd> A 32 bit padding field; with the <var>pad1</var> field, lengthens the structure to 64 bits. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_qos</strong> structure is used to specify a port's "quality of service" attributes when allocating the port via the <strong>mach_port_allocate_qos</strong> interface. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate_qos.html"><strong>mach_port_allocate_qos</strong></a>, <a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>, <a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>. \ No newline at end of file +<h2>mach_port_qos</h2> +<hr> +<p> +<strong>Structure</strong> - Specifies a port's attributes with respect to "Quality Of Service." +<h3>SYNOPSIS</h3> +<pre> +<strong>typedef struct mach_port_qos</strong> + <strong>{</strong> + <strong>boolean_t</strong> <var>name</var><strong>;</strong> + <strong>boolean_t</strong> <var>rt</var><strong>;</strong> + <strong>boolean_t</strong> <var>pad1</var><strong>;</strong> + <strong>boolean_t</strong> <var>pad2</var><strong>;</strong> + <strong>} mach_port_qos_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>name</var> +<dd> + If TRUE, the system will bestow the user-specified name on the newly allocated port. + Otherwise, the system will choose the port's name. + <p> + <dt> <var>rt</var> +<dd> + If TRUE, this field causes a realtime port to be allocated. + Otherwise, a regular port will be allocated. +<p> + <dt> <var>pad1</var> +<dd> + A 30 bit padding field. +<p> + <dt> <var>pad2</var> +<dd> +A 32 bit padding field; with the <var>pad1</var> field, lengthens the + structure to 64 bits. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_qos</strong> structure is used to specify a port's +"quality of service" attributes when allocating the port via the +<strong>mach_port_allocate_qos</strong> interface. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate_qos.html"><strong>mach_port_allocate_qos</strong></a>, +<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>, +<a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>. diff --git a/osfmk/man/mach_port_set_attributes.html b/osfmk/man/mach_port_set_attributes.html index 9b3f9c183..59792bdd8 100755 --- a/osfmk/man/mach_port_set_attributes.html +++ b/osfmk/man/mach_port_set_attributes.html @@ -1 +1,78 @@ -<h2>mach_port_set_attributes</h2> <hr> <p> <strong>Function</strong> - Set the target port's attributes. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_set_attributes</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_port_flavor_t</strong> <var>flavor</var>, <strong>mach_port_info_t</strong> <var>port_info</var>, <strong>mach_msg_type_number_t</strong> <var>port_info_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task holding a receive right to the port in question. <p> <dt> <var>name</var> <dd> [in scalar] <var>task</var>'s name for the port. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of attributes to be set. Valid values are: <dl> <p> <dt> <strong>MACH_PORT_LIMITS_INFO</strong> <dd> Sets resource limits (queue limits) for the port. The declaration of this data is found in structure <strong>mach_port_limits</strong>. </dl> <p> <dt> <var>port_info</var> <dd> [pointer to in structure] Attributes for the specified port. <p> <dt> <var>port_info_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_set_attributes</strong> function sets attributes of type <var>flavor</var>. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> <var>name</var> did not denote a right. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> <var>name</var> denoted a right, but not a receive right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, <a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, <a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>. <p> Data Structures: <a href="mach_port_limits.html"><strong>mach_port_limits</strong></a>. \ No newline at end of file +<h2>mach_port_set_attributes</h2> +<hr> +<p> +<strong>Function</strong> - Set the target port's attributes. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_set_attributes</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_port_flavor_t</strong> <var>flavor</var>, + <strong>mach_port_info_t</strong> <var>port_info</var>, + <strong>mach_msg_type_number_t</strong> <var>port_info_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task holding a receive right to the port in +question. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +<var>task</var>'s name for the port. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of attributes to be set. Valid values are: +<dl> +<p> +<dt> <strong>MACH_PORT_LIMITS_INFO</strong> +<dd> +Sets resource limits (queue limits) for the port. The declaration +of this data is found in structure <strong>mach_port_limits</strong>. +</dl> +<p> +<dt> <var>port_info</var> +<dd> +[pointer to in structure] +Attributes for the specified port. +<p> +<dt> <var>port_info_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_set_attributes</strong> function sets attributes of type +<var>flavor</var>. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +<var>name</var> did not denote a right. +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +<var>name</var> denoted a right, but not a receive right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, +<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, +<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>. +<p> +Data Structures: +<a href="mach_port_limits.html"><strong>mach_port_limits</strong></a>. diff --git a/osfmk/man/mach_port_set_mscount.html b/osfmk/man/mach_port_set_mscount.html index d42f8eb82..c427702a6 100755 --- a/osfmk/man/mach_port_set_mscount.html +++ b/osfmk/man/mach_port_set_mscount.html @@ -1 +1,57 @@ -<h2>mach_port_set_mscount</h2> <hr> <p> <strong>Function</strong> - Change the target port's make-send count. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_set_mscount</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task owning the receive right. <p> <dt> <var>name</var> <dd> [in scalar] <var>task</var>'s name for the receive right. <p> <dt> <var>mscount</var> <dd> [in scalar] New value for the make-send count for the receive right. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_set_mscount</strong> function changes the make-send count of <var>task</var>'s receive right named <var>name</var>. A port's make-send count specifies the number of send rights that have been generated via the port's receive right. A port's make-send count is set to zero when the port is first allocated; the count is reset to zero each time the port's receive right is transferred via a Mach message. <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> <var>name</var> did not denote a right. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> <var>name</var> denoted a right, but not a receive right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>. \ No newline at end of file +<h2>mach_port_set_mscount</h2> +<hr> +<p> +<strong>Function</strong> - Change the target port's make-send count. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_set_mscount</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task owning the receive right. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +<var>task</var>'s name for the receive right. +<p> +<dt> <var>mscount</var> +<dd> +[in scalar] +New value for the make-send count for the receive right. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_set_mscount</strong> function changes the make-send +count of <var>task</var>'s +receive right named <var>name</var>. +A port's make-send count specifies the number of send rights that have +been generated via the port's receive right. A port's make-send count +is set to zero when the port is first allocated; the count is reset to +zero each time the port's receive right is transferred via a Mach message. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +<var>name</var> did not denote a right. +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +<var>name</var> denoted a right, but not a receive right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>. diff --git a/osfmk/man/mach_port_set_seqno.html b/osfmk/man/mach_port_set_seqno.html index 4871b1fac..ee34bf560 100755 --- a/osfmk/man/mach_port_set_seqno.html +++ b/osfmk/man/mach_port_set_seqno.html @@ -1 +1,60 @@ -<h2>mach_port_set_seqno</h2> <hr> <p> <strong>Function</strong> - Change the current value of the target port's sequence number. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_set_seqno</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task owning the receive right. <p> <dt> <var>name</var> <dd> [in scalar] <var>task</var>'s name for the receive right. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number that the next message received from the port will have. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_set_seqno</strong> function changes the sequence number of <var>task</var>'s receive right named <var>name</var>. <p> (Each port is associated with a sequence number attribute that can be used to track the order in which messages sent to the port are received. A port's sequence number is initially set to zero and is incremented each time a message is received from the port. A port's sequence number is automatically reset to zero each time the port's receive right migrates.) <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> <var>name</var> did not denote a right. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> <var>name</var> denoted a right, but not a receive right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>. \ No newline at end of file +<h2>mach_port_set_seqno</h2> +<hr> +<p> +<strong>Function</strong> - Change the current value of the target port's sequence number. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_set_seqno</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task owning the receive right. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +<var>task</var>'s name for the receive right. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number that the next message received from +the port will have. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_set_seqno</strong> function changes the sequence +number of <var>task</var>'s +receive right named <var>name</var>. +<p> +(Each port is associated with a sequence number attribute that can be +used to track the order in which messages sent to the port are received. +A port's sequence number is initially set to zero and is incremented each +time a message is received from the port. A port's sequence number is +automatically reset to zero each time the port's receive right migrates.) +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +<var>name</var> did not denote a right. +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +<var>name</var> denoted a right, but not a receive right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>. diff --git a/osfmk/man/mach_port_status.html b/osfmk/man/mach_port_status.html index 649a4132a..1e9b8d74e 100755 --- a/osfmk/man/mach_port_status.html +++ b/osfmk/man/mach_port_status.html @@ -1 +1,95 @@ -<h2>mach_port_status</h2> <hr> <p> <strong>Structure</strong> - Used to present a port's current status with respect to various important attributes. <h3>SYNOPSIS</h3> <pre> <strong>struct mach_port_status</strong> <strong>{</strong> <strong>natural_t</strong> <var>mps_pset_count</var><strong>;</strong> <strong>mach_port_seqno_t</strong> <var>mps_seqno</var><strong>;</strong> <strong>mach_port_mscount_t</strong> <var>mps_mscount</var><strong>;</strong> <strong>mach_port_msgcount_t</strong> <var>mps_qlimit</var><strong>;</strong> <strong>mach_port_msgcount_t</strong> <var>mps_msgcount</var><strong>;</strong> <strong>mach_port_rights_t</strong> <var>mps_sorights</var><strong>;</strong> <strong>mach_port_srights_t</strong> <var>mps_srights</var><strong>;</strong> <strong>boolean_t</strong> <var>mps_pdrequest</var><strong>;</strong> <strong>boolean_t</strong> <var>mps_nsrequest</var><strong>;</strong> <strong>unsigned int</strong> <var>mps_flags</var><strong>;</strong> <strong>};</strong> <strong>typedef struct mach_port_status mach_port_status_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>mps_pset</var> <dd> Containing port set. <p> <dt> <var>mps_seqno</var> <dd> Current sequence number for the port. <p> <dt> <var>mps_mscount</var> <dd> Make-send count. <p> <dt> <var>mps_msgcount</var> <dd> Upper limit for the number of messages that may be queued to the port before the system blocks send operations. <p> <dt> <var>mps_msgcount</var> <dd> Number of messages currently queued on the port. <p> <dt> <var>mps_sorights</var> <dd> How many send-once rights. <p> <dt> <var>mps_srights</var> <dd> Specifies whether or not send rights exist. Valid values are as follows: <dl> <p> <dt> MPS_FALSE <dd> No send rights currently in existence. <p> <dt> MPS_TRUE <dd> Send rights exist and no-more-senders notification is enabled. <p> <dt> MPS_UNKNOWN <dd> The port does not permit no-more-senders notification requests; consequently, the system does not know whether or not send rights exist. </dl> <p> <dt> <var>mps_pdrequest</var> <dd> Specifies whether or not a port-deleted notification has been requested. <p> <dt> <var>mps_nsrequest</var> <dd> True if no-senders requested. <p> <dt> <var>mps_flags</var> <dd> Flags associated with the port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_status</strong> structure is used to provide information about a port in response to an invocation of the <strong>mach_port_get_attributes</strong> interface. <h3>NOTES</h3> <p> This structure is machine word length sensitive due to the presence of the port set name. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>. \ No newline at end of file +<h2>mach_port_status</h2> +<hr> +<p> +<strong>Structure</strong> - Used to present a port's current status with respect to various important attributes. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct mach_port_status</strong> +<strong>{</strong> + <strong>natural_t</strong> <var>mps_pset_count</var><strong>;</strong> + <strong>mach_port_seqno_t</strong> <var>mps_seqno</var><strong>;</strong> + <strong>mach_port_mscount_t</strong> <var>mps_mscount</var><strong>;</strong> + <strong>mach_port_msgcount_t</strong> <var>mps_qlimit</var><strong>;</strong> + <strong>mach_port_msgcount_t</strong> <var>mps_msgcount</var><strong>;</strong> + <strong>mach_port_rights_t</strong> <var>mps_sorights</var><strong>;</strong> + <strong>mach_port_srights_t</strong> <var>mps_srights</var><strong>;</strong> + <strong>boolean_t</strong> <var>mps_pdrequest</var><strong>;</strong> + <strong>boolean_t</strong> <var>mps_nsrequest</var><strong>;</strong> + <strong>unsigned int</strong> <var>mps_flags</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct mach_port_status mach_port_status_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>mps_pset</var> +<dd> +Containing port set. + <p> +<dt> <var>mps_seqno</var> +<dd> +Current sequence number for the port. + <p> + <dt> <var>mps_mscount</var> + <dd> + Make-send count. + <p> +<dt> <var>mps_msgcount</var> +<dd> +Upper limit for the number of messages that may be queued to the port + before the system blocks send operations. + <p> + <dt> <var>mps_msgcount</var> +<dd> + Number of messages currently queued on the port. + <p> +<dt> <var>mps_sorights</var> +<dd> +How many send-once rights. + <p> +<dt> <var>mps_srights</var> +<dd> +Specifies whether or not send rights exist. Valid values are as follows: + <dl> + <p> + <dt> MPS_FALSE + <dd> + No send rights currently in existence. + <p> + <dt> MPS_TRUE + <dd> + Send rights exist and no-more-senders notification is enabled. + <p> + <dt> MPS_UNKNOWN + <dd> + The port does not permit no-more-senders notification requests; + consequently, the system does not know whether or not send rights + exist. + </dl> + <p> +<dt> <var>mps_pdrequest</var> +<dd> + Specifies whether or not a port-deleted notification has been requested. + <p> +<dt> <var>mps_nsrequest</var> +<dd> +True if no-senders requested. + <p> +<dt> <var>mps_flags</var> +<dd> + Flags associated with the port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_status</strong> structure is used to provide +information about a port in response to an invocation of the +<strong>mach_port_get_attributes</strong> interface. +<h3>NOTES</h3> +<p> +This structure is machine word length sensitive due +to the presence of the port +set name. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>. diff --git a/osfmk/man/mach_port_type.html b/osfmk/man/mach_port_type.html index 524828e16..5d7ee4d5b 100755 --- a/osfmk/man/mach_port_type.html +++ b/osfmk/man/mach_port_type.html @@ -1 +1,79 @@ -<h2>mach_port_type</h2> <hr> <p> <strong>Function</strong> - Return the characteristics of the target port name. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_port_type</strong> <strong>(ipc_space_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>name</var>, <strong>mach_port_type_t</strong> <var>ptype</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task whose port name space is queried. <p> <dt> <var>name</var> <dd> [in scalar] The name being queried. <p> <dt> <var>ptype</var> <dd> [out scalar] The type of the name. Indicates what kind of right the task holds for the port, port set, or dead name. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_port_type</strong> function returns information about <var>task</var>'s rights for a specific name in its port name space. The returned <var>ptype</var> is a bit-mask indicating what rights <var>task</var> holds with this name. The bit-mask is composed of the following bits: <dl> <dt> <strong>MACH_PORT_TYPE_SEND</strong> <dd> The name denotes send rights. <p> <dt> <strong>MACH_PORT_TYPE_RECEIVE</strong> <dd> The name denotes a receive right. <p> <dt> <strong>MACH_PORT_TYPE_SEND_ONCE</strong> <dd> The name denotes a send-once right. <p> <dt> <strong>MACH_PORT_TYPE_PORT_SET</strong> <dd> The name denotes a port set. <p> <dt> <strong>MACH_PORT_TYPE_DEAD_NAME</strong> <dd> The name is a dead name. <p> <dt> <strong>MACH_PORT_TYPE_DNREQUEST</strong> <dd> A dead-name request has been registered for the right. </dl> <h3>NOTES</h3> <p> This interface is machine word length specific because of the port name parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_NAME</strong> <dd> <var>name</var> did not denote a right. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_names.html"><strong>mach_port_names</strong></a>, <a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>, <a href="mach_port_get_set_status.html"><strong>mach_port_get_set_status</strong></a>. \ No newline at end of file +<h2>mach_port_type</h2> +<hr> +<p> +<strong>Function</strong> - Return the characteristics of the target port name. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_port_type</strong> + <strong>(ipc_space_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>name</var>, + <strong>mach_port_type_t</strong> <var>ptype</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task whose port name space is queried. +<p> +<dt> <var>name</var> +<dd> +[in scalar] +The name being queried. +<p> +<dt> <var>ptype</var> +<dd> +[out scalar] +The type of the name. Indicates what kind of right the task +holds for the port, port set, or dead name. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_port_type</strong> function returns information about <var>task</var>'s +rights for a specific name in its port name space. The returned +<var>ptype</var> is a bit-mask indicating what rights <var>task</var> +holds with this name. +The bit-mask is composed of the following bits: +<dl> +<dt> <strong>MACH_PORT_TYPE_SEND</strong> +<dd> +The name denotes send rights. +<p> +<dt> <strong>MACH_PORT_TYPE_RECEIVE</strong> +<dd> +The name denotes a receive right. +<p> +<dt> <strong>MACH_PORT_TYPE_SEND_ONCE</strong> +<dd> +The name denotes a send-once right. +<p> +<dt> <strong>MACH_PORT_TYPE_PORT_SET</strong> +<dd> +The name denotes a port set. +<p> +<dt> <strong>MACH_PORT_TYPE_DEAD_NAME</strong> +<dd> +The name is a dead name. +<p> +<dt> <strong>MACH_PORT_TYPE_DNREQUEST</strong> +<dd> +A dead-name request has been registered for the right. +</dl> +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the port name +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_NAME</strong> +<dd> +<var>name</var> did not denote a right. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_names.html"><strong>mach_port_names</strong></a>, +<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>, +<a href="mach_port_get_set_status.html"><strong>mach_port_get_set_status</strong></a>. diff --git a/osfmk/man/mach_ports_lookup.html b/osfmk/man/mach_ports_lookup.html index 907e81cd7..9016b589c 100755 --- a/osfmk/man/mach_ports_lookup.html +++ b/osfmk/man/mach_ports_lookup.html @@ -1 +1,49 @@ -<h2>mach_ports_lookup</h2> <hr> <p> <strong>Function</strong> - Provide caller with an array of the target task's well-known ports. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_ports_lookup</strong> <strong>(task_t</strong> <var>target_task</var>, <strong>mach_port_array_t</strong> <var>init_port_set</var>, <strong>mach_msg_type_number_t</strong> <var>init_port_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The task whose currently registered ports are to be returned. <p> <dt> <var>init_port_set</var> <dd> [out pointer to dynamic array of registered send rights] The returned array of ports. <p> <dt> <var>init_port_count</var> <dd> [out scalar] The number of returned port rights. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_ports_lookup</strong> function returns an array of the well-known system ports that are currently registered for the specified task. Note that the task holds only send rights for the ports. <p> Registered ports are those ports that are used by the run-time system to initialize a task. To register system ports for a task, use the <strong>mach_ports_register</strong> function. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_ports_register.html"><strong>mach_ports_register</strong></a>. \ No newline at end of file +<h2>mach_ports_lookup</h2> +<hr> +<p> +<strong>Function</strong> - Provide caller with an array of the target task's well-known ports. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_ports_lookup</strong> + <strong>(task_t</strong> <var>target_task</var>, + <strong>mach_port_array_t</strong> <var>init_port_set</var>, + <strong>mach_msg_type_number_t</strong> <var>init_port_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The task whose currently registered ports are to be +returned. +<p> +<dt> <var>init_port_set</var> +<dd> +[out pointer to dynamic array of registered send rights] +The returned +array of ports. +<p> +<dt> <var>init_port_count</var> +<dd> +[out scalar] +The number of returned port rights. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_ports_lookup</strong> function returns an array of +the well-known system +ports that are currently registered for the specified task. +Note that the task holds +only send rights for the ports. +<p> +Registered ports are those ports that are used by the run-time +system to initialize a task. To register system ports for a task, +use the <strong>mach_ports_register</strong> function. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_ports_register.html"><strong>mach_ports_register</strong></a>. diff --git a/osfmk/man/mach_ports_register.html b/osfmk/man/mach_ports_register.html index 03f21b5e5..cbb92d754 100755 --- a/osfmk/man/mach_ports_register.html +++ b/osfmk/man/mach_ports_register.html @@ -1 +1,115 @@ -<h2>mach_ports_register</h2> <hr> <p> <strong>Function</strong> - Register an array of well-known ports on behalf of the target task. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_ports_register</strong> <strong>(task_t</strong> <var>target_task</var>, <strong>mach_port_array_t</strong> <var>init_port_set</var>, <strong>target_task</strong> <var>init_port_array_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The task for which the ports are to be registered. <p> <dt> <var>init_port_set</var> <dd> [in pointer to array of registered send rights] The array of ports to register. <p> <dt> <var>init_port_array_count</var> <dd> [in scalar] The number of ports in the array. Note that while this is a variable, the kernel accepts only a limited number of ports. The maximum number of ports is defined by the global constant <strong>MACH_PORTS_SLOTS_USED</strong>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_ports_register</strong> function registers an array of well-known system ports for the specified task. The task holds only send rights for the registered ports. The valid well-known system ports are: <ul> <li> The port for the Name Server <li> The port for the Environment Manager <li> The port for the Service server </ul> <p> Each port must be placed in a specific slot in the array. The slot numbers are defined (in <strong>mach.h</strong>) by the global constants <strong>NAME_SERVER_SLOT</strong>, <strong>ENVIRONMENT_SLOT</strong>, and <strong>SERVICE_SLOT</strong>. <p> A task can retrieve the currently registered ports by using the <strong>mach_ports_lookup</strong> function. <h3>NOTES</h3> <p> When a new task is created (with <strong>task_create</strong>), the child task can inherit the parent's registered ports. Note that child tasks do not automatically acquire rights to these ports. They must use <strong>mach_ports_lookup</strong> to get them. It is intended that port registration be used only for task initialization, and then only by run-time support modules. <p> A parent task has three choices when passing registered ports to child tasks: <ul> <li> The parent task can do nothing. In this case, all child tasks inherit access to the same ports that the parent has. <li> The parent task can use <strong>mach_ports_register</strong> to modify its set of registered ports before creating child tasks. In this case, the child tasks get access to the modified set of ports. After creating its child tasks. the parent can use <strong>mach_ports_register</strong> again to reset its registered ports. <li> The parent task can first create a specific child task and then use <strong>mach_ports_register</strong> to modify the child's inherited set of ports, before starting the child's thread(s). The parent must specify the child's task port, rather than its own, on the call to <strong>mach_ports_register</strong>. </ul> <p> Tasks other than the Name Server and the Environment Manager should not need access to the Service port. The Name Server port is the same for all tasks on a given machine. The Environment port is the only port likely to have different values for different tasks. <p> Registered ports are restricted to those ports that are used by the run-time system to initialize a task. A parent task can pass other ports to its child tasks through: <ul> <li> An initial message (see <strong>mach_msg</strong>). <li> The Name Server, for public ports. <li> The Environment Manager, for private ports. <li> The task bootstrap port (see <strong>task_get_special_port</strong>). </ul> <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="mach_ports_lookup.html"><strong>mach_ports_lookup</strong></a>. \ No newline at end of file +<h2>mach_ports_register</h2> +<hr> +<p> +<strong>Function</strong> - Register an array of well-known ports on behalf of the target task. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_ports_register</strong> + <strong>(task_t</strong> <var>target_task</var>, + <strong>mach_port_array_t</strong> <var>init_port_set</var>, + <strong>target_task</strong> <var>init_port_array_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The task for which the ports are to be registered. +<p> +<dt> <var>init_port_set</var> +<dd> +[in pointer to array of registered send rights] +The array of ports to +register. +<p> +<dt> <var>init_port_array_count</var> +<dd> +[in scalar] +The number of ports in the array. Note that while this is a +variable, the kernel accepts only a limited number of ports. The +maximum number of ports is defined by the global constant +<strong>MACH_PORTS_SLOTS_USED</strong>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_ports_register</strong> function registers an array +of well-known system +ports for the specified task. The task holds only send rights +for the registered +ports. The valid well-known system ports are: +<ul> +<li> +The port for the Name Server +<li> +The port for the Environment Manager +<li> +The port for the Service server +</ul> +<p> +Each port must be placed in a specific slot in the array. The slot numbers are +defined (in <strong>mach.h</strong>) by the global constants <strong>NAME_SERVER_SLOT</strong>, +<strong>ENVIRONMENT_SLOT</strong>, and <strong>SERVICE_SLOT</strong>. +<p> +A task can retrieve the currently registered ports by using the +<strong>mach_ports_lookup</strong> function. +<h3>NOTES</h3> +<p> +When a new task is created (with <strong>task_create</strong>), +the child task can inherit the +parent's registered ports. Note that child tasks do not automatically +acquire rights +to these ports. They must use <strong>mach_ports_lookup</strong> to +get them. It is intended +that port registration be used only for task initialization, and then only by +run-time support modules. +<p> +A parent task has three choices when passing registered ports to child tasks: +<ul> +<li> +The parent task can do nothing. In this case, all child tasks +inherit access to +the same ports that the parent has. +<li> +The parent task can use <strong>mach_ports_register</strong> to modify +its set of registered +ports before creating child tasks. In this case, the child tasks get access +to the +modified set of ports. After creating its child tasks. the parent can use +<strong>mach_ports_register</strong> again to reset its registered ports. +<li> +The parent task can first create a specific child task and then use +<strong>mach_ports_register</strong> to modify the child's inherited +set of ports, before starting +the child's thread(s). The parent must specify the child's task port, rather +than its own, on the call to <strong>mach_ports_register</strong>. +</ul> +<p> +Tasks other than the Name Server and the Environment Manager +should not need access to the Service port. The Name Server port is +the same for all tasks on a given machine. The Environment port +is the only port +likely to have different values for different tasks. +<p> +Registered ports are restricted to those ports that are used by the run-time +system to initialize a task. A parent task can pass other ports +to its child tasks +through: +<ul> +<li> +An initial message (see <strong>mach_msg</strong>). +<li> +The Name Server, for public ports. +<li> +The Environment Manager, for private ports. +<li> +The task bootstrap port (see <strong>task_get_special_port</strong>). +</ul> +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_msg.html"><strong>mach_msg</strong></a>, +<a href="mach_ports_lookup.html"><strong>mach_ports_lookup</strong></a>. diff --git a/osfmk/man/mach_reply_port.html b/osfmk/man/mach_reply_port.html index f2355b72a..55200fb56 100755 --- a/osfmk/man/mach_reply_port.html +++ b/osfmk/man/mach_reply_port.html @@ -1 +1,51 @@ -<h2>mach_reply_port</h2> <hr> <p> <strong>System Trap</strong> - Allocate a new port and insert corresponding receive right in the calling task. <h3>SYNOPSIS</h3> <pre> <strong>#include<mach/mach_traps.h></strong> <strong>mach_port_t mach_reply_port( void )</strong> </pre> <h3>PARAMETERS</h3> <dl> None. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_reply_port</strong> function creates a new port for the current task and returns the name assigned by the kernel. The kernel records the name in the task's port name space and grants the task receive rights for the port. The new port is not a member of any port set. <p> This function is an optimized version of <strong>mach_port_allocate</strong> that uses no port references. Its main purpose is to allocate a reply port for the task when the task is starting, for example, before it has any ports to use as reply ports for any IPC-based system functions. <p> If the task's task self port is null (thereby deactivating basic Mach manipulations by the task), this call returns null. <h3>CAUTIONS</h3> <p> Although the created port can be used for any purpose, the implementation may optimize its use as a reply port. <h3>RETURN VALUES</h3> <dl> <dt> <strong>MACH_PORT_NULL</strong> <dd> No port was allocated. <p> <dt> [reply receive right] <dd> Any other value indicates success. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>. \ No newline at end of file +<h2>mach_reply_port</h2> +<hr> +<p> +<strong>System Trap</strong> - Allocate a new port and insert corresponding receive right in the calling task. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<mach/mach_traps.h></strong> + +<strong>mach_port_t mach_reply_port( void )</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +None. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_reply_port</strong> function creates a new port for +the current task and +returns the name assigned by the kernel. The kernel records +the name in the task's +port name space and grants the task receive rights for the port. +The new port is +not a member of any port set. +<p> +This function is an optimized version of <strong>mach_port_allocate</strong> +that uses no port +references. Its main purpose is to allocate a reply port for +the task when the task +is starting, for example, before it has any ports to use as reply +ports for any IPC-based system functions. +<p> +If the task's task self port is null (thereby deactivating basic Mach +manipulations by the task), this call returns null. +<h3>CAUTIONS</h3> +<p> +Although the created port can be used for any purpose, the implementation may +optimize its use as a reply port. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>MACH_PORT_NULL</strong> +<dd> +No port was allocated. + <p> +<dt> [reply receive right] +<dd> +Any other value indicates success. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>. diff --git a/osfmk/man/mach_rpc_return_trap.html b/osfmk/man/mach_rpc_return_trap.html index 3202fee17..182851f73 100755 --- a/osfmk/man/mach_rpc_return_trap.html +++ b/osfmk/man/mach_rpc_return_trap.html @@ -1 +1,33 @@ -<h2>mach_rpc_return_trap</h2> <hr> <p> <strong>System Trap</strong> - Real-Time RPC trap return location. <h3>SYNOPSIS</h3> <pre> <strong>#include<mach/rpc.h></strong> <strong>mach_rpc_return_t mach_rpc_return_trap( void )</strong> </pre> <h3>PARAMETERS</h3> <p> None. <h3>DESCRIPTION</h3> <p> The <strong>mach_rpc_return_trap</strong> is the system entry point used by the reply side of the Mach RPC service and is used by RPC servers to return control to invoking clients. For a complete description of this functionality, refer to: Burke, Edward, Michael Condict, David Mitchell, Franklin Reynolds, Peter Watkins, William Willcox, "RPC Design for Real-Time Mach," OSF Research Institute, Cambridge, MA. <h3>NOTES</h3> <p> This interface is experimental and therefore subject to change. <h3>RETURN VALUES</h3> <p> The return value is specific to the server function actually executed via the <strong>mach_rpc_return_trap</strong> call. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_rpc_trap.html"><strong>mach_rpc_trap</strong></a>. \ No newline at end of file +<h2>mach_rpc_return_trap</h2> +<hr> +<p> +<strong>System Trap</strong> - Real-Time RPC trap return location. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<mach/rpc.h></strong> + +<strong>mach_rpc_return_t mach_rpc_return_trap( void )</strong> +</pre> +<h3>PARAMETERS</h3> +<p> +None. +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_rpc_return_trap</strong> is the system entry point +used by the reply side of the Mach RPC service and is used by RPC +servers to return control to invoking clients. +For a complete description of this functionality, refer to: Burke, +Edward, Michael Condict, David Mitchell, Franklin Reynolds, Peter +Watkins, William Willcox, "RPC Design for Real-Time Mach," OSF +Research Institute, Cambridge, MA. +<h3>NOTES</h3> +<p> +This interface is experimental and therefore subject to change. +<h3>RETURN VALUES</h3> +<p> +The return value is specific to the server function actually executed +via the <strong>mach_rpc_return_trap</strong> call. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_rpc_trap.html"><strong>mach_rpc_trap</strong></a>. diff --git a/osfmk/man/mach_rpc_trap.html b/osfmk/man/mach_rpc_trap.html index 5a0038229..fc2f8347d 100755 --- a/osfmk/man/mach_rpc_trap.html +++ b/osfmk/man/mach_rpc_trap.html @@ -1 +1,83 @@ -<h2>mach_rpc_trap</h2> <hr> <p> <strong>System Trap</strong> - Real-Time RPC trap. <h3>SYNOPSIS</h3> <pre> <strong>#include<mach/rpc.h></strong> <strong>mach_rpc_return_t mach_rpc_trap</strong> <strong>(mach_port_t</strong> <var>dest_port</var>, <strong>mach_rpc_id_t</strong> <var>routine_num</var>, <strong>mach_rpc_signature_t</strong> <var>signature_ptr</var>, <strong>mach_rpc_size_t</strong> <var>signature_size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>dest_port</var> <dd> [in send right] The port representing the destination of the RPC (usually a registered subsystem established by a call to <strong>mach_port_allocate_subsystem</strong>). <p> <dt> <var>routine_num</var> <dd> [in scalar] Identifier of the server work function. <p> <dt> <var>signature_ptr</var> <dd> [in pointer] Pointer to the call's <strong>mach_rpc_signature</strong> structure. <p> <dt> <var>signature_size</var> <dd> [in scalar] Size, in bytes, of the call's <strong>mach_rpc_signature</strong> structure. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_rpc_trap</strong> system trap is the entry point for the invoke side of the Mach RPC service used to transfer control to an RPC server. The trap is accessed via the MIG generated <strong>MACH_RPC</strong> macro which is invoked transparently when the <strong>mach_rpc</strong> feature is enabled. This function is not designed for use directly by the user. It is automatically generated by MIG to handle a function call. <p> For a complete description of this functionality, refer to: Burke, Edward, Michael Condict, David Mitchell, Franklin Reynolds, Peter Watkins, William Willcox, "RPC Design for Real-Time Mach," OSF Research Institute, Cambridge, MA. <h3>NOTES</h3> <p> This interface is experimental and therefore subject to change. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_FAILURE</strong> <dd> Either the argument copyin failed, there were too many arguments, or the argument copyout failed. <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The dest_port, signature_ptr, and/or the subsystem associated with the dest_port is invalid; the siganture_size is less than, or equal to, zero. <p> <dt> <strong>KERN_NO_ACCESS</strong> <dd> The kernel port associated with the dest_port name is a norma proxy port. <p> <dt> <strong>KERN_RESOURCE_SHORTAGE</strong> <dd> The kernel could not allocate storage for an internal rpc state structure. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_rpc_return_trap.html"><strong>mach_rpc_return_trap</strong></a>, <a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>, <a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>, <a href="mach_subsystem_create.html"><strong>mach_subsystem_create</strong></a>. \ No newline at end of file +<h2>mach_rpc_trap</h2> +<hr> +<p> +<strong>System Trap</strong> - Real-Time RPC trap. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<mach/rpc.h></strong> + +<strong>mach_rpc_return_t mach_rpc_trap</strong> + <strong>(mach_port_t</strong> <var>dest_port</var>, + <strong>mach_rpc_id_t</strong> <var>routine_num</var>, + <strong>mach_rpc_signature_t</strong> <var>signature_ptr</var>, + <strong>mach_rpc_size_t</strong> <var>signature_size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>dest_port</var> +<dd> +[in send right] The port representing the destination of the RPC + (usually a registered subsystem established by a call to + <strong>mach_port_allocate_subsystem</strong>). +<p> +<dt> <var>routine_num</var> +<dd> +[in scalar] Identifier of the server work function. +<p> +<dt> <var>signature_ptr</var> +<dd> +[in pointer] Pointer to the call's <strong>mach_rpc_signature</strong> structure. +<p> +<dt> <var>signature_size</var> +<dd> +[in scalar] Size, in bytes, of the call's <strong>mach_rpc_signature</strong> structure. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_rpc_trap</strong> system trap is the entry point for the +invoke side of the Mach RPC service used to transfer control to an RPC server. +The trap is accessed via the MIG generated +<strong>MACH_RPC</strong> macro +which is invoked transparently when the <strong>mach_rpc</strong> feature is enabled. +This function is not designed for use directly by the user. It is +automatically generated by MIG to handle a function call. +<p> +For a +complete description of this functionality, refer to: Burke, Edward, +Michael Condict, David Mitchell, Franklin Reynolds, Peter Watkins, +William Willcox, "RPC Design for Real-Time Mach," OSF Research +Institute, Cambridge, MA. +<h3>NOTES</h3> +<p> +This interface is experimental and therefore subject to change. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_FAILURE</strong> +<dd> +Either the argument copyin failed, there were too many arguments, or +the argument copyout failed. +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The dest_port, signature_ptr, and/or the subsystem associated with the +dest_port is invalid; the siganture_size is less than, or equal to, zero. +<p> +<dt> <strong>KERN_NO_ACCESS</strong> +<dd> +The kernel port associated with the dest_port name is a norma proxy +port. +<p> +<dt> <strong>KERN_RESOURCE_SHORTAGE</strong> +<dd> +The kernel could not allocate storage for an internal rpc state +structure. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_rpc_return_trap.html"><strong>mach_rpc_return_trap</strong></a>, +<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>, +<a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>, +<a href="mach_subsystem_create.html"><strong>mach_subsystem_create</strong></a>. diff --git a/osfmk/man/mach_subsystem_create.html b/osfmk/man/mach_subsystem_create.html index 9f13b905f..3240b2e43 100755 --- a/osfmk/man/mach_subsystem_create.html +++ b/osfmk/man/mach_subsystem_create.html @@ -1 +1,88 @@ -<h2>mach_subsystem_create</h2> <hr> <p> <strong>Function</strong> - Register information about an RPC subsystem. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t mach_subsystem_create</strong> <strong>(task_t</strong> <var>target_task</var>, <strong>user_subsystem_t</strong> <var>user_subsys</var>, <strong>mach_msg_type_number_t</strong> <var>user_subsysCnt</var>, <strong>subsystem_t</strong> <var>subsystem_t</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> The task for which the subsystem is registered; normally the calling task, but not necessarily. <p> <dt> <var>user_subsys</var> <dd> The MIG-generated data structure describing the exported routines and their input/output characteristics (e.g. arguments and return values). <p> <dt> <var>user_subsysCnt</var> <dd> The size of the user_subsys data structure argument, in bytes. <p> <dt> <var>subsys</var> <dd> The port returned that names the registered subsystem. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mach_subsystem_create</strong> function is used by a server to register information about an RPC subsystem with the kernel. MIG automatically generates, in the server source file, a <strong>user_subsystem_t</strong> data structure that is appropriate for registering the subsystem. This data structure includes a per-routine array that specifies: <ul> <li> The address of the server function that performs the work. <li> The address of the MIG-generated server-side marshalling stub, to be used with <strong>mach_msg</strong>. <li> The argument signature (i.e. NDR-style argument format) of the routine. </ul> <p> Upon successful completion, <strong>mach_subsystem_create</strong> returns, via the <var>subsys</var> parameter, a port naming the registered subsystem. <p> Each port on which the server is to receive short-circuited RPC's (or a <strong>mach_rpc</strong> call) must be associated with a registered subsystem, by calling <strong>mach_port_allocate_subsystem</strong>. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALD_ADDRESS</strong> <dd> One or more of the addresses in the range specified by the subsystem address and size are not valid addresses in the caller, or some of the internal pointers in the subsystem do not point to places within the address range (all of the data of the subsystem is required to be contiguous, even the parts that are pointed to by other parts). <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The port name specified by <var>target_task</var> is not a send right naming a task, or the subsystem size is too small to be valid. <p> <dt> <strong>KERN_INVALID_TASK</strong> <dd> The target task is dead. <p> <dt> <strong>KERN_RESOURCE_SHORTAGE</strong> <dd> The kernel cannot allocate the subsystem due to insufficient available memory. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>, <a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>. \ No newline at end of file +<h2>mach_subsystem_create</h2> +<hr> +<p> +<strong>Function</strong> - Register information about an RPC subsystem. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t mach_subsystem_create</strong> + <strong>(task_t</strong> <var>target_task</var>, + <strong>user_subsystem_t</strong> <var>user_subsys</var>, + <strong>mach_msg_type_number_t</strong> <var>user_subsysCnt</var>, + <strong>subsystem_t</strong> <var>subsystem_t</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +The task for which the subsystem is registered; normally the calling +task, but not necessarily. +<p> +<dt> <var>user_subsys</var> +<dd> +The MIG-generated data structure describing the exported routines and +their input/output characteristics (e.g. arguments and return values). +<p> +<dt> <var>user_subsysCnt</var> +<dd> +The size of the user_subsys data structure argument, in bytes. +<p> +<dt> <var>subsys</var> +<dd> +The port returned that names the registered subsystem. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_subsystem_create</strong> function is used by a server to register +information about an RPC subsystem with the kernel. +MIG automatically generates, in the server source file, a +<strong>user_subsystem_t</strong> data structure that is appropriate for registering +the subsystem. This data structure includes a per-routine array that +specifies: +<ul> +<li> +The address of the server function that performs the work. +<li> +The address of the MIG-generated server-side marshalling stub, to be +used with <strong>mach_msg</strong>. +<li> +The argument signature (i.e. NDR-style argument format) of the +routine. +</ul> +<p> +Upon successful completion, <strong>mach_subsystem_create</strong> returns, +via the <var>subsys</var> parameter, a port naming the registered subsystem. +<p> +Each port on which the server is to receive short-circuited RPC's (or +a <strong>mach_rpc</strong> call) must be associated with a registered subsystem, by +calling <strong>mach_port_allocate_subsystem</strong>. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALD_ADDRESS</strong> +<dd> +One or more of the addresses in the range specified by the subsystem +address and size are not valid addresses in the caller, or some of the +internal pointers in the subsystem do not point to places within the +address range (all of the data of the subsystem is required to be +contiguous, even the parts that are pointed to by other parts). +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The port name specified by <var>target_task</var> is not a send right naming a task, +or the subsystem size is too small to be valid. +<p> +<dt> <strong>KERN_INVALID_TASK</strong> +<dd> +The target task is dead. +<p> +<dt> <strong>KERN_RESOURCE_SHORTAGE</strong> +<dd> +The kernel cannot allocate the subsystem due to insufficient available +memory. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>, +<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>. diff --git a/osfmk/man/mach_task_self.html b/osfmk/man/mach_task_self.html index 130c7e264..a887717da 100755 --- a/osfmk/man/mach_task_self.html +++ b/osfmk/man/mach_task_self.html @@ -1 +1,31 @@ -<h2>mach_task_self</h2> <hr> <p> <strong>System Trap</strong> - Return a send right to the caller's task_self port. <h3>SYNOPSIS</h3> <pre> <strong>#include<mach/mach_traps.h></strong> <strong>mach_port_t mach_task_self (void)</strong> </pre> <h3>PARAMETERS</h3> <p> None. <h3>DESCRIPTION</h3> <p> The <strong>mach_task_self</strong> function returns send rights to the task's kernel port. <h3>NOTES</h3> <p> This function call is redefined in the <strong>mach_init.h</strong> file to return the caller's <strong>mach_task_self_</strong> environment variable, which is cached on behalf of the caller's task at runtime. (The <strong>mach_init.h</strong> file is itself included via the <strong>mach.h</strong> file. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>. \ No newline at end of file +<h2>mach_task_self</h2> +<hr> +<p> +<strong>System Trap</strong> - Return a send right to the caller's task_self port. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<mach/mach_traps.h></strong> + +<strong>mach_port_t mach_task_self (void)</strong> +</pre> +<h3>PARAMETERS</h3> +<p> +None. +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_task_self</strong> function returns send rights to +the task's kernel port. +<h3>NOTES</h3> +<p> +This function call is redefined in the <strong>mach_init.h</strong> file +to return the caller's <strong>mach_task_self_</strong> environment variable, +which is cached on behalf of the caller's task at runtime. +(The <strong>mach_init.h</strong> file is itself included via the +<strong>mach.h</strong> file. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>. diff --git a/osfmk/man/mach_thread_self.html b/osfmk/man/mach_thread_self.html index 6472709d7..c4eec79d3 100755 --- a/osfmk/man/mach_thread_self.html +++ b/osfmk/man/mach_thread_self.html @@ -1 +1,27 @@ -<h2>mach_thread_self</h2> <hr> <p> <strong>System Trap</strong> - Returns the thread self port. <h3>SYNOPSIS</h3> <p> <strong>#include <mach/mach_traps.h></strong> <pre> <strong>thread_port_t mach_thread_self( void );</strong> </pre> <h3>PARAMETERS</h3> <p> None. <h3>DESCRIPTION</h3> <p> The <strong>mach_thread_self</strong> function returns send rights to the thread's own kernel port. <h3>RETURN VALUES</h3> <p> [thread-self send right] Send rights to the thread's port. <h3>RELATED INFORMATION<h3> <p> Functions: <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>. \ No newline at end of file +<h2>mach_thread_self</h2> +<hr> +<p> +<strong>System Trap</strong> - Returns the thread self port. + +<h3>SYNOPSIS</h3> +<p> +<strong>#include <mach/mach_traps.h></strong> +<pre> +<strong>thread_port_t mach_thread_self( void );</strong> +</pre> +<h3>PARAMETERS</h3> +<p> +None. +<h3>DESCRIPTION</h3> +<p> +The <strong>mach_thread_self</strong> function returns send rights +to the thread's own kernel port. +<h3>RETURN VALUES</h3> +<p> +[thread-self send right] Send rights to the thread's port. +<h3>RELATED INFORMATION<h3> +<p> +Functions: +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>. + diff --git a/osfmk/man/mapped_tvalspec.html b/osfmk/man/mapped_tvalspec.html index 972941b15..43e970a3d 100755 --- a/osfmk/man/mapped_tvalspec.html +++ b/osfmk/man/mapped_tvalspec.html @@ -1 +1,54 @@ -<h2>mapped_tvalspec</h2> <hr> <p> <strong>Structure</strong> - Specifies the format the kernel uses to maintain a mapped clock's time. <h3>SYNOPSIS</h3> <pre> <strong>struct mapped_tvalspec</strong> <strong>{</strong> <strong>tvalspec_t</strong> <var>mtv_time</var><strong>;</strong> <strong>unsigned int</strong> <var>mtv_csec</var><strong>;</strong> <strong>};</strong> <strong>typedef struct mapped_tvalspec mapped_tvalspec_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>mtv_time</var> <dd> Clock time. <p> <dt> <var>mtv_csec</var> <dd> A field used to synchronize with the kernel's setting of the time. </dl> <h3>DESCRIPTION</h3> <p> The <strong>mapped_tvalspec</strong> structure defines the format of the current-time structure maintained by the kernel and visible through a mapped clock (<strong>clock_map_time</strong>). The data in this structure is updated at the clock's current resolution and contains the same <strong>tvalspec</strong> value that would be returned by <strong>clock_get_time</strong>. <h3>NOTES</h3> <p> Because of the race between the referencing of the multiple fields in the clock value and the kernel's setting them, they should be referenced as follows: <p> <pre> <strong>tvalspec_t* ts;</strong> <strong>do</strong> <strong>{</strong> <strong>ts-> tv_sec = mtime -> mtv_time.tv_sec;</strong> <strong>ts -> tv_nsec = mtime -> mtv_time.tv_nsec;</strong> <strong>} while (ts -> tv_sec != mtime -> mtv_csec);</strong> </pre> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="clock_map_time.html"><strong>clock_map_time</strong></a>, <a href="clock_get_time.html"><strong>clock_get_time</strong></a>. <p> Data Structures: <a href="tvalspec.html"><strong>tvalspec</strong></a>. \ No newline at end of file +<h2>mapped_tvalspec</h2> +<hr> +<p> +<strong>Structure</strong> - Specifies the format the kernel uses to maintain a mapped clock's time. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct mapped_tvalspec</strong> +<strong>{</strong> + <strong>tvalspec_t</strong> <var>mtv_time</var><strong>;</strong> + <strong>unsigned int</strong> <var>mtv_csec</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct mapped_tvalspec mapped_tvalspec_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>mtv_time</var> +<dd> +Clock time. +<p> +<dt> <var>mtv_csec</var> +<dd> +A field used to synchronize with the kernel's setting of the time. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>mapped_tvalspec</strong> structure defines the format of the +current-time structure +maintained by the kernel and visible through a mapped clock +(<strong>clock_map_time</strong>). The data in this structure is updated at the +clock's current resolution and contains the same <strong>tvalspec</strong> value that +would be returned by <strong>clock_get_time</strong>. +<h3>NOTES</h3> +<p> +Because of the race between the referencing of the multiple fields +in the clock +value and the kernel's setting them, they should be referenced as follows: +<p> +<pre> + <strong>tvalspec_t* ts;</strong> + <strong>do</strong> + <strong>{</strong> + <strong>ts-> tv_sec = mtime -> mtv_time.tv_sec;</strong> + <strong>ts -> tv_nsec = mtime -> mtv_time.tv_nsec;</strong> + <strong>} while (ts -> tv_sec != mtime -> mtv_csec);</strong> +</pre> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="clock_map_time.html"><strong>clock_map_time</strong></a>, +<a href="clock_get_time.html"><strong>clock_get_time</strong></a>. +<p> +Data Structures: +<a href="tvalspec.html"><strong>tvalspec</strong></a>. diff --git a/osfmk/man/memory_object_attr_info.html b/osfmk/man/memory_object_attr_info.html index dcd0d42c0..7f94e44f1 100755 --- a/osfmk/man/memory_object_attr_info.html +++ b/osfmk/man/memory_object_attr_info.html @@ -1 +1,84 @@ -<h2>memory_object_attr_info</h2> <hr> <p> <strong>Structure</strong> - Specifies memory object's behavior attributes. <h3>SYNOPSIS</h3> <pre> <strong>struct memory_object_attr_info</strong> <strong>{</strong> <strong>memory_object_copy_strategy_t</strong> <var>copy_strategy</var><strong>;</strong> <strong>vm_offset_t</strong> <var>cluster_size</var><strong>;</strong> <strong>boolean_t</strong> <var>may_cache</var><strong>;</strong> <strong>boolean_t</strong> <var>temporary</var><strong>;</strong> <strong>};</strong> <strong>typedef struct memory_object_attr_info* memory_object_attr_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>copy_strategy</var> <dd> How the kernel should handle copying of regions associated with the memory object. The copy strategy cannot be changed once an object is initialized. Valid values are: <dl> <p> <dt> <strong>MEMORY_OBJECT_COPY_NONE</strong> <dd> Use normal procedure when copying the memory object's data. Normally, the kernel requests each page with read access, copies the data, and then (optionally) flushes the data. <p> <dt> <strong>MEMORY_OBJECT_COPY_CALL</strong> <dd> Call the memory manager when a copy operation is necessary. <p> <dt> <strong>MEMORY_OBJECT_COPY_DELAY</strong> <dd> Use copy-on-write technique. This strategy allows the kernel to efficiently copy large amounts of data and guarantees that the memory manager will not externally modify the data. It is the most commonly used copy strategy. <p> <dt> <strong>MEMORY_OBJECT_COPY_TEMPORARY</strong> <dd> All changes are made in memory and the memory manager does not need to see them. <p> <dt> <strong>MEMORY_OBJECT_COPY_SYMMETRIC</strong> <dd> The memory manager does not change the data, does not need to see any changes to the data, and will prevent the object from being mapped more than once. Currently, this strategy should be restricted to use by the kernel. </dl> <p> <dt> <var>cluster_size</var> <dd> The memory object's perferred cluster size (in bytes). This value may affect the number of pages transferred in a given paging operation. <p> <dt> <var>may_cache</var> <dd> Cache indicator. If true, the kernel can cache data associated with the memory object (keep the memory object active) even if no virtual memory references to it remain. <p> <dt> <var>temporary</var> <dd> If TRUE, when the last mapping to the object is released, the kernel destroys the object without returning any resident pages. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_attr_info</strong> structure defines behavior and performance relevant memory object attributes. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>, <a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>, <a href="vm_region.html"><strong>vm_region</strong></a>, <a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>, <a href="VSD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>, <a href="vm_msync.html"><strong>vm_msync</strong></a>. \ No newline at end of file +<h2>memory_object_attr_info</h2> +<hr> +<p> +<strong>Structure</strong> - Specifies memory object's behavior attributes. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct memory_object_attr_info</strong> +<strong>{</strong> + <strong>memory_object_copy_strategy_t</strong> <var>copy_strategy</var><strong>;</strong> + <strong>vm_offset_t</strong> <var>cluster_size</var><strong>;</strong> + <strong>boolean_t</strong> <var>may_cache</var><strong>;</strong> + <strong>boolean_t</strong> <var>temporary</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct memory_object_attr_info* memory_object_attr_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>copy_strategy</var> +<dd> +How the kernel should handle copying of regions associated with the +memory object. The copy strategy cannot be changed once an object is +initialized. Valid values are: +<dl> +<p> +<dt> <strong>MEMORY_OBJECT_COPY_NONE</strong> +<dd> +Use normal procedure when copying the memory object's +data. Normally, the kernel requests each page with read +access, copies the data, and then (optionally) flushes the data. +<p> +<dt> <strong>MEMORY_OBJECT_COPY_CALL</strong> +<dd> +Call the memory manager when a copy operation is necessary. +<p> +<dt> <strong>MEMORY_OBJECT_COPY_DELAY</strong> +<dd> +Use copy-on-write technique. This strategy allows the kernel +to efficiently copy large amounts of data and guarantees that +the memory manager will not externally modify the data. It is +the most commonly used copy strategy. +<p> +<dt> <strong>MEMORY_OBJECT_COPY_TEMPORARY</strong> +<dd> +All changes are made in memory and the memory manager does not need +to see them. +<p> +<dt> <strong>MEMORY_OBJECT_COPY_SYMMETRIC</strong> +<dd> +The memory manager does not change the data, does not need to see +any changes to the data, and will prevent the object from being +mapped more than once. Currently, this strategy should be restricted +to use by the kernel. +</dl> +<p> +<dt> <var>cluster_size</var> +<dd> +The memory object's perferred cluster size (in bytes). This value may affect +the number of pages transferred in a given paging operation. +<p> +<dt> <var>may_cache</var> +<dd> +Cache indicator. If true, the kernel can cache data associated with the +memory object (keep the memory object active) even if no virtual +memory references to it remain. +<p> +<dt> <var>temporary</var> +<dd> +If TRUE, when the last mapping to the object is released, +the kernel destroys the object without returning any resident pages. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_attr_info</strong> structure defines behavior and +performance relevant memory object attributes. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>, +<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>, +<a href="vm_region.html"><strong>vm_region</strong></a>, +<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>, +<a href="VSD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>, +<a href="vm_msync.html"><strong>vm_msync</strong></a>. diff --git a/osfmk/man/memory_object_create.html b/osfmk/man/memory_object_create.html index 89ebee320..c09fae18e 100755 --- a/osfmk/man/memory_object_create.html +++ b/osfmk/man/memory_object_create.html @@ -1 +1,119 @@ -<h2>memory_object_create</h2> <hr> <p> <strong>Function</strong> - Request that the default pager handle management requests on the specified memory object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_create</strong> <strong>(memory_object_t</strong> <var>pager</var>, <strong>memory_object_t</strong> <var>new_memory_object</var>, <strong>vm_size_t</strong> <var>new_object_size</var>, <strong>memory_object_control_t</strong> <var>new_control</var>, <strong>vm_size_t</strong> <var>new_page_size</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_create</strong> <strong>(memory_object_t</strong> <var>pager</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_t</strong> <var>new_memory_object</var>, <strong>vm_size_t</strong> <var>new_object_size</var>, <strong>memory_object_control_t</strong> <var>new_control</var>, <strong>vm_size_t</strong> <var>new_page_size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>pager</var> <dd> [in default-pager (receive) right] The default memory manager service port. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the pager port. <p> <dt> <var>new_memory_object</var> <dd> [in abstract-memory-object receive right] The port representing the new abstract memory object created by the kernel. <p> <dt> <var>new_object_size</var> <dd> [in scalar] The expected size for the new object, in bytes. <p> <dt> <var>new_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used by the memory manager when making cache management requests for the new object. <p> <dt> <var>new_page_size</var> <dd> [in scalar] The page size used by the kernel. All calls involving this kernel must use data sizes that are integral multiples of this page size. </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_create</strong> function is called as the result of a message from the kernel requesting that the default memory manager accept responsibility for the new memory object created by the kernel. The kernel makes this call only to the system default memory manager. <p> The new memory object initially consists of zero-filled pages. Only memory pages that are actually written are provided to the memory manager. When processing <strong>memory_object_data_request</strong> calls from the kernel, the default memory manager must use <strong>memory_object_data_unavailable</strong> for any pages that have not been written previously. <p> The kernel does not expect a reply to this call. The kernel assumes that the default memory manager will be ready to handle data requests to this object and does not need the confirmation of a <strong>memory_object_change_attributes</strong> call. <h3>NOTES</h3> <p> The kernel requires memory objects to provide temporary backing storage for zero-filled memory created by <strong>vm_allocate</strong> calls, issued by both user tasks and the kernel itself. The kernel allocates an abstract memory object port to represent the temporary backing storage and uses <strong>memory_object_create</strong> to pass the new memory object to the default memory manager, which provides the storage. <p> The default memory manager is a trusted system component that is identified to the kernel at system initialization time. The default memory manager can also be changed at run time using the <strong>host_default_memory_manager</strong> call. <p> The contents of a kernel-created (as opposed to a user-created) memory object can be modified only in main memory. The default memory manager must not change the contents of a temporary memory object, or allow unrelated tasks to access the memory object, control, or name port. <p> The kernel provides the size of a temporary memory object based on the allocated size. Since the object is not mapped by other tasks, the object will not grow by explicit action. However, the kernel may coalesce adjacent temporary objects in such a way that this object may appear to grow. As such, the supplied object size is merely a hint as to the maximum size. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="DP_object_create.html"><strong>default_pager_object_create</strong></a>, <a href="MO_data_initialize.html"><strong>memory_object_data_initialize</strong></a>, <a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>, <a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>, <a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>. \ No newline at end of file +<h2>memory_object_create</h2> +<hr> +<p> +<strong>Function</strong> - Request that the default pager handle management requests on the specified memory object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_create</strong> + <strong>(memory_object_t</strong> <var>pager</var>, + <strong>memory_object_t</strong> <var>new_memory_object</var>, + <strong>vm_size_t</strong> <var>new_object_size</var>, + <strong>memory_object_control_t</strong> <var>new_control</var>, + <strong>vm_size_t</strong> <var>new_page_size</var><strong>);</strong> + + +<strong>kern_return_t seqnos_memory_object_create</strong> + <strong>(memory_object_t</strong> <var>pager</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_t</strong> <var>new_memory_object</var>, + <strong>vm_size_t</strong> <var>new_object_size</var>, + <strong>memory_object_control_t</strong> <var>new_control</var>, + <strong>vm_size_t</strong> <var>new_page_size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>pager</var> +<dd> +[in default-pager (receive) right] +The default memory manager service +port. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the pager +port. +<p> +<dt> <var>new_memory_object</var> +<dd> +[in abstract-memory-object receive right] +The port representing the +new abstract memory object created by the kernel. +<p> +<dt> <var>new_object_size</var> +<dd> +[in scalar] +The expected size for the new object, in bytes. +<p> +<dt> <var>new_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used by the memory manager when making cache management +requests for the new object. +<p> +<dt> <var>new_page_size</var> +<dd> +[in scalar] +The page size used by the kernel. All calls involving this +kernel must use data sizes that are integral multiples of this page size. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_create</strong> function is called as the result +of a message from the +kernel requesting that the default memory manager accept responsibility +for the +new memory object created by the kernel. The kernel makes this +call only to the +system default memory manager. +<p> +The new memory object initially consists of zero-filled pages. Only memory +pages that are actually written are provided to the memory manager. When +processing <strong>memory_object_data_request</strong> calls from the +kernel, the default +memory manager must use <strong>memory_object_data_unavailable</strong> +for any pages that have not been written previously. +<p> +The kernel does not expect a reply to this call. The kernel assumes that the +default memory manager will be ready to handle data requests to this object and +does not need the confirmation of a <strong>memory_object_change_attributes</strong> call. +<h3>NOTES</h3> +<p> +The kernel requires memory objects to provide temporary backing storage for +zero-filled memory created by <strong>vm_allocate</strong> calls, issued +by both user tasks and +the kernel itself. The kernel allocates an abstract memory object port to +represent the temporary backing storage and uses <strong>memory_object_create</strong> +to pass the +new memory object to the default memory manager, which provides the storage. +<p> +The default memory manager is a trusted system component that is identified to +the kernel at system initialization time. The default memory manager can also +be changed at run time using the <strong>host_default_memory_manager</strong> call. +<p> +The contents of a kernel-created (as opposed to a user-created) memory object +can be modified only in main memory. The default memory manager must not +change the contents of a temporary memory object, or allow unrelated tasks to +access the memory object, control, or name port. +<p> +The kernel provides the size of a temporary memory object based on the +allocated size. Since the object is not mapped by other tasks, +the object will not grow +by explicit action. However, the kernel may coalesce adjacent +temporary objects +in such a way that this object may appear to grow. As such, +the supplied object +size is merely a hint as to the maximum size. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="DP_object_create.html"><strong>default_pager_object_create</strong></a>, +<a href="MO_data_initialize.html"><strong>memory_object_data_initialize</strong></a>, +<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>, +<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>, +<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>. diff --git a/osfmk/man/memory_object_data_error.html b/osfmk/man/memory_object_data_error.html index 804b3027a..0f487a875 100755 --- a/osfmk/man/memory_object_data_error.html +++ b/osfmk/man/memory_object_data_error.html @@ -1 +1,70 @@ -<h2>memory_object_data_error</h2> <hr> <p> <strong>Function</strong> - An error prevents the supply of previously requested data. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_data_error</strong> <strong>(memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>kern_return_t</strong> <var>reason</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used by the memory manager for cache management requests. This port is provided by the kernel in a <strong>memory_object_create</strong> call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object, in bytes. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes of data (starting at <var>offset</var>). The number must convert to an integral number of memory object pages. <p> <dt> <var>reason</var> <dd> [in scalar] Reason for the error. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_data_error</strong> function indicates that the memory manager cannot provide the kernel with the data requested for the given region, specifying a reason for the error. <p> When the kernel issues a <strong>memory_object_data_request</strong> call, the memory manager can respond with a <strong>memory_object_data_error</strong> call to indicate that the page cannot be retrieved, and that a memory failure exception should be raised in any client threads that are waiting for the page. Clients are permitted to catch these exceptions and retry their page faults. As a result, this call can be used to report transient errors as well as permanent ones. A memory manager can use this call for both hardware errors (for example, disk failures) and software errors (for example, accessing data that does not exist or is protected). <h3>NOTES</h3> <p> If reason has a system code of <var>err_kern</var>, the kernel will substitute an error value of <strong>KERN_MEMORY_ERROR</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>, <a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>, <a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>. \ No newline at end of file +<h2>memory_object_data_error</h2> +<hr> +<p> +<strong>Function</strong> - An error prevents the supply of previously requested data. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_data_error</strong> + <strong>(memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>kern_return_t</strong> <var>reason</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used by the memory manager for cache management requests. +This port is provided by the kernel in a <strong>memory_object_create</strong> call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object, in bytes. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes of data (starting at <var>offset</var>). The number +must convert to an integral number of memory object pages. +<p> +<dt> <var>reason</var> +<dd> +[in scalar] +Reason for the error. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_data_error</strong> function indicates that +the memory manager +cannot provide the kernel with the data requested for the given region, +specifying a reason for the error. +<p> +When the kernel issues a <strong>memory_object_data_request</strong> call, the memory +manager can respond with a <strong>memory_object_data_error</strong> +call to indicate that the +page cannot be retrieved, and that a memory failure exception should be raised +in any client threads that are waiting for the page. Clients +are permitted to catch +these exceptions and retry their page faults. As a result, this +call can be used to +report transient errors as well as permanent ones. A memory manager can use +this call for both hardware errors (for example, disk failures) and software +errors (for example, accessing data that does not exist or is protected). +<h3>NOTES</h3> +<p> +If reason has a system code of <var>err_kern</var>, the kernel will substitute +an error value +of <strong>KERN_MEMORY_ERROR</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>, +<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>, +<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>. diff --git a/osfmk/man/memory_object_data_request.html b/osfmk/man/memory_object_data_request.html index 2b3dbcb88..26181b358 100755 --- a/osfmk/man/memory_object_data_request.html +++ b/osfmk/man/memory_object_data_request.html @@ -1 +1,113 @@ -<h2>memory_object_data_request</h2> <hr> <p> <strong>Server Interface</strong> - Request that memory manager page-in specified data. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_data_request</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>length</var>, <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_data_request</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>length</var>, <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_object</var> <dd> [in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the abstract memory object port. <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used for a response by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object. <p> <dt> <var>length</var> <dd> [in scalar] The number of bytes requested, starting at <var>offset</var>. The number converts to an integral number of virtual pages. <p> <dt> <var>desired_access</var> <dd> [in scalar] The memory access modes to be allowed for the cached data. Possible values are obtained by or'ing together the following values: <dl> <p> <dt> <strong>VM_PROT_READ</strong> <dd> Allows read access. <p> <dt> <strong>VM_PROT_WRITE</strong> <dd> Allows write access. <p> <dt> <strong>VM_PROT_EXECUTE</strong> <dd> Allows execute access. </dl> </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_data_request</strong> function is called as the result of a kernel message requesting data from the specified memory object, for at least the access specified. <p> The kernel issues this call after a cache miss (that is, a page fault for which the kernel does not have the data). The kernel requests only amounts of data that are multiples of the page size included in the <strong>memory_object_init</strong> or <strong>memory_object_create</strong> call. <p> The memory manager is expected to use <strong>memory_object_data_supply</strong> to return at least the specified data, with as much access as it can allow. If the memory manager cannot provide the data (for example, because of a hardware error), it can use the <strong>memory_object_data_error</strong> call. The memory manager can also use <strong>memory_object_data_unavailable</strong> to tell the kernel to supply zero-filled memory for the region. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>, <a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>, <a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>, <a href="memory_object_server.html"><strong>memory_object_server</strong></a>, <a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. \ No newline at end of file +<h2>memory_object_data_request</h2> +<hr> +<p> +<strong>Server Interface</strong> - Request that memory manager page-in specified data. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_data_request</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>length</var>, + <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong> + + +<strong>kern_return_t seqnos_memory_object_data_request</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>length</var>, + <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_object</var> +<dd> +[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the abstract +memory object port. +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used for a response by the memory manager. If the memory +object has been supplied to more than one kernel, this parameter +identifies the kernel that is making the call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object. +<p> +<dt> <var>length</var> +<dd> +[in scalar] +The number of bytes requested, starting at <var>offset</var>. The +number converts to an integral number of virtual pages. +<p> +<dt> <var>desired_access</var> +<dd> +[in scalar] +The memory access modes to be allowed for the cached +data. Possible values are obtained by or'ing together the following +values: +<dl> +<p> +<dt> <strong>VM_PROT_READ</strong> +<dd> +Allows read access. +<p> +<dt> <strong>VM_PROT_WRITE</strong> +<dd> +Allows write access. +<p> +<dt> <strong>VM_PROT_EXECUTE</strong> +<dd> +Allows execute access. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_data_request</strong> function is called as +the result of a kernel +message requesting data from the specified memory object, for at least the +access specified. +<p> +The kernel issues this call after a cache miss (that is, a page +fault for which the +kernel does not have the data). The kernel requests only amounts +of data that are +multiples of the page size included in the +<strong>memory_object_init</strong> or <strong>memory_object_create</strong> call. +<p> +The memory manager is expected to use <strong>memory_object_data_supply</strong> to +return at least the specified data, with as much access as it +can allow. If the +memory manager cannot provide the data (for example, because +of a hardware error), +it can use the <strong>memory_object_data_error</strong> call. The +memory manager can also +use <strong>memory_object_data_unavailable</strong> to tell the kernel +to supply zero-filled +memory for the region. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>, +<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>, +<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>, +<a href="memory_object_server.html"><strong>memory_object_server</strong></a>, +<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. + diff --git a/osfmk/man/memory_object_data_return.html b/osfmk/man/memory_object_data_return.html index 38abcef38..96de61daf 100755 --- a/osfmk/man/memory_object_data_return.html +++ b/osfmk/man/memory_object_data_return.html @@ -1 +1,102 @@ -<h2>memory_object_data_return</h2> <hr> <p> <strong>Server Interface</strong> - Return memory object data to the appropriate memory manager. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_data_return</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>pointer_t</strong> <var>data</var>, <strong>boolean_t</strong> <var>dirty</var>, <strong>boolean_t</strong> <var>kernel_copy</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_data_return</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>pointer_t</strong> <var>data</var>, <strong>boolean_t</strong> <var>dirty</var>, <strong>boolean_t</strong> <var>kernel_copy</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_object</var> <dd> [in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the abstract memory object port. <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used for a response by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object. <p> <dt> <var>data</var> <dd> [in pointer to dynamic array of bytes] The data that has been evicted from the physical memory cache. <p> <dt> <var>dirty</var> <dd> [in scalar] If <strong>TRUE</strong>, the pages returned have been modified. <p> <dt> <var>kernel_copy</var> <dd> [in scalar] If <strong>TRUE</strong>, the kernel has kept a copy of the page. </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_data_return</strong> function is called as the result of a kernel message providing the memory manager with data that has been evicted from the physical memory cache. <p> The kernel writes back only data that has been modified or is precious. When the memory manager no longer needs the data (for example, after the data has been written to permanent storage), it should use <strong>vm_deallocate</strong> to release the memory resources. <h3>NOTES</h3> <p> The kernel can flush clean (that is, un-modified) non-precious pages at its own discretion. As a result, the memory manager cannot rely on the kernel to keep a copy of its data or even to provide notification that its data has been discarded. <p> The kernel may re-request the returned data at any time following this message (including immediately). <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>, <a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, <a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>, <a href="memory_object_server.html"><strong>memory_object_server</strong></a>, <a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. \ No newline at end of file +<h2>memory_object_data_return</h2> +<hr> +<p> +<strong>Server Interface</strong> - Return memory object data to the appropriate memory manager. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_data_return</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>pointer_t</strong> <var>data</var>, + <strong>boolean_t</strong> <var>dirty</var>, + <strong>boolean_t</strong> <var>kernel_copy</var><strong>);</strong> + + +<strong>kern_return_t seqnos_memory_object_data_return</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>pointer_t</strong> <var>data</var>, + <strong>boolean_t</strong> <var>dirty</var>, + <strong>boolean_t</strong> <var>kernel_copy</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_object</var> +<dd> +[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the abstract +memory object port. +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used for a response by the memory manager. If the memory +object has been supplied to more than one kernel, this parameter +identifies the kernel that is making the call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object. +<p> +<dt> <var>data</var> +<dd> +[in pointer to dynamic array of bytes] +The data that has been evicted +from the physical memory cache. +<p> +<dt> <var>dirty</var> +<dd> +[in scalar] +If <strong>TRUE</strong>, the pages returned have been modified. +<p> +<dt> <var>kernel_copy</var> +<dd> +[in scalar] +If <strong>TRUE</strong>, the kernel has kept a copy of the page. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_data_return</strong> function is called as the +result of a kernel +message providing the memory manager with data that has been evicted from the +physical memory cache. +<p> +The kernel writes back only data that has been modified or is precious. When +the memory manager no longer needs the data (for example, after the data has +been written to permanent storage), it should use <strong>vm_deallocate</strong> +to release the +memory resources. +<h3>NOTES</h3> +<p> +The kernel can flush clean (that is, un-modified) non-precious +pages at its own +discretion. As a result, the memory manager cannot rely on the +kernel to keep a +copy of its data or even to provide notification that its data +has been discarded. +<p> +The kernel may re-request the returned data at any time following this message +(including immediately). +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>, +<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, +<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>, +<a href="memory_object_server.html"><strong>memory_object_server</strong></a>, +<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. diff --git a/osfmk/man/memory_object_data_supply.html b/osfmk/man/memory_object_data_supply.html index 961d523f0..4c1478872 100755 --- a/osfmk/man/memory_object_data_supply.html +++ b/osfmk/man/memory_object_data_supply.html @@ -1 +1,140 @@ -<h2>memory_object_data_supply</h2> <hr> <p> <strong>Function</strong> - Provide kernel with data previously requested by the kernel's Memory Management facility. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_data_supply</strong> <strong>(mem_object_control_port_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>pointer_t</strong> <var>data</var>, <strong>mach_msg_type_number_t</strong> <var>data_count</var>, <strong>boolean_t</strong> <var>deallocate</var>, <strong>vm_prot_t</strong> <var>lock_value</var>, <strong>boolean_t</strong> <var>precious</var>, <strong>mach_port_t</strong> <var>reply_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used by the memory manager for cache management requests. This port is provided by the kernel in a <strong>memory_object_init</strong> or <strong>memory_object_create</strong> call. <p> <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object, in bytes. <p> <p> <dt> <var>data</var> <dd> [pointer to page aligned in array of bytes] The address of the data being provided to the kernel. <p> <p> <dt> <var>data_count</var> <dd> [in scalar] The amount of data to be provided. The number must be an integral number of memory object pages. <p> <p> <dt> <var>deallocate</var> <dd> [in scalar] If <strong>TRUE</strong>, the pages to be copied (starting at data) will be deallocated from the memory manager's address space as a result of being copied into the message, allowing the pages to be moved into the kernel instead of being physically copied. <p> <p> <dt> <var>lock_value</var> <dd> [in scalar] One or more forms of access <var>not</var> permitted for the specified data. Valid values are: <dl> <p> <p> <dt> <strong>VM_PROT_NONE</strong> <dd> Prohibits no access (that is, all forms of access are permitted). <p> <p> <dt> <strong>VM_PROT_READ</strong> <dd> Prohibits read access. <p> <p> <dt> <strong>VM_PROT_WRITE</strong> <dd> Prohibits write access. <p> <p> <dt> <strong>VM_PROT_EXECUTE</strong> <dd> Prohibits execute access. <p> <p> <dt> <strong>VM_PROT_ALL</strong> <dd> Prohibits all forms of access. </dl> <p> <p> <dt> <var>precious</var> <dd> [in scalar] If <strong>TRUE</strong>, the pages being supplied are "precious," that is, the memory manager is not (necessarily) retaining its own copy. These pages must be returned to the manager when evicted from memory, even if not modified. <p> <p> <dt> <var>reply_port</var> <dd> [in reply receive (to be converted to send) right] A port to which the kernel should send a <strong>memory_object_supply_completed</strong> to indicate the status of the accepted data. <strong>MACH_PORT_NULL</strong> is allowed. The reply message indicates which pages have been accepted. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_data_supply</strong> function supplies the kernel with a range of data for the specified memory object. A memory manager can only provide data that was requested by a <strong>memory_object_data_request</strong> call from the kernel. <h3>NOTES</h3> <p> The kernel accepts only integral numbers of pages. It discards any partial pages without notification. <h3>CAUTIONS</h3> <p> A memory manager must be careful that it not attempt to provide data that has not been explicitly requested. In particular, a memory manager must ensure that it does not provide writable data again before it receives back modifications from the kernel. This may require that the memory manager remember which pages it has provided, or that it exercise other cache control functions (via <strong>memory_object_lock_request</strong>) before proceeding. The kernel prohibits the overwriting of live data pages and will not accept pages it has not requested. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>, <a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>, <a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>, <a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>, <a href="MO_supply_completed.html"><strong>memory_object_supply_completed</strong></a>. \ No newline at end of file +<h2>memory_object_data_supply</h2> +<hr> +<p> +<strong>Function</strong> - Provide kernel with data previously requested by the kernel's Memory Management facility. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_data_supply</strong> + <strong>(mem_object_control_port_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>pointer_t</strong> <var>data</var>, + <strong>mach_msg_type_number_t</strong> <var>data_count</var>, + <strong>boolean_t</strong> <var>deallocate</var>, + <strong>vm_prot_t</strong> <var>lock_value</var>, + <strong>boolean_t</strong> <var>precious</var>, + <strong>mach_port_t</strong> <var>reply_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used by the memory manager for cache management requests. +This port is provided by the kernel in a <strong>memory_object_init</strong> + or <strong>memory_object_create</strong> call. +<p> +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object, in bytes. +<p> +<p> +<dt> <var>data</var> +<dd> +[pointer to page aligned in array of bytes] +The address of the data +being provided to the kernel. +<p> +<p> +<dt> <var>data_count</var> +<dd> +[in scalar] +The amount of data to be provided. The number must be an +integral number of memory object pages. +<p> +<p> +<dt> <var>deallocate</var> +<dd> +[in scalar] +If <strong>TRUE</strong>, the pages to be copied (starting at data) will be +deallocated from the memory manager's address space as a result of +being copied into the message, allowing the pages to be moved into the +kernel instead of being physically copied. +<p> +<p> +<dt> <var>lock_value</var> +<dd> +[in scalar] +One or more forms of access <var>not</var> permitted for the specified +data. Valid values are: +<dl> +<p> +<p> +<dt> <strong>VM_PROT_NONE</strong> +<dd> +Prohibits no access (that is, all forms of access are permitted). +<p> +<p> +<dt> <strong>VM_PROT_READ</strong> +<dd> +Prohibits read access. +<p> +<p> +<dt> <strong>VM_PROT_WRITE</strong> +<dd> +Prohibits write access. +<p> +<p> +<dt> <strong>VM_PROT_EXECUTE</strong> +<dd> +Prohibits execute access. +<p> +<p> +<dt> <strong>VM_PROT_ALL</strong> +<dd> +Prohibits all forms of access. +</dl> +<p> +<p> +<dt> <var>precious</var> +<dd> +[in scalar] +If <strong>TRUE</strong>, the pages being supplied are "precious," that is, +the memory manager is not (necessarily) retaining its own copy. These +pages must be returned to the manager when evicted from memory, +even if not modified. +<p> +<p> +<dt> <var>reply_port</var> +<dd> +[in reply receive (to be converted to send) right] +A port to which the +kernel should send a <strong>memory_object_supply_completed</strong> to indicate +the status of the accepted data. <strong>MACH_PORT_NULL</strong> is allowed. The +reply message indicates which pages have been accepted. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_data_supply</strong> function supplies the +kernel with a range of +data for the specified memory object. A memory manager can only provide data +that was requested by a <strong>memory_object_data_request</strong> +call from the kernel. +<h3>NOTES</h3> +<p> +The kernel accepts only integral numbers of pages. It discards +any partial pages +without notification. +<h3>CAUTIONS</h3> +<p> +A memory manager must be careful that it not attempt to provide data that has +not been explicitly requested. In particular, a memory manager +must ensure that +it does not provide writable data again before it receives back modifications +from the kernel. This may require that the memory manager remember which +pages it has provided, or that it exercise other cache control functions (via +<strong>memory_object_lock_request</strong>) before proceeding. The kernel prohibits the +overwriting of live data pages and will not accept pages it has not requested. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>, +<a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>, +<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>, +<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>, +<a href="MO_supply_completed.html"><strong>memory_object_supply_completed</strong></a>. diff --git a/osfmk/man/memory_object_data_unlock.html b/osfmk/man/memory_object_data_unlock.html index 13a440c9a..76e95a5ea 100755 --- a/osfmk/man/memory_object_data_unlock.html +++ b/osfmk/man/memory_object_data_unlock.html @@ -1 +1,96 @@ -<h2>memory_object_data_unlock</h2> <hr> <p> <strong>Server Interface</strong> - Request that the memory manager change current access permission on the specified memory object's data. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_data_unlock</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>length</var>, <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_data_unlock</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>length</var>, <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_object</var> <dd> [in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the abstract memory object port. <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used for a response by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object. <p> <dt> <var>length</var> <dd> [in scalar] The number of bytes to which the access applies, starting at <var>offset</var>. The number converts to an integral number of memory object pages. <p> <dt> <var>desired_access</var> <dd> [in scalar] The memory access modes requested for the cached data. Possible values are obtained by or'ing together the following values: <dl> <p> <dt> <strong>VM_PROT_READ</strong> <dd> Allows read access. <p> <dt> <strong>VM_PROT_WRITE</strong> <dd> Allows write access. <p> <dt> <strong>VM_PROT_EXECUTE</strong> <dd> Allows execute access. </dl> </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_data_unlock</strong> function is called as the result of a kernel message requesting the memory manager to permit at least the desired access to the specified data cached by the kernel. The memory manager is expected to use the <strong>memory_object_lock_request</strong> call in response. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>, <a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>, <a href="memory_object_server.html"><strong>memory_object_server</strong></a>, <a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. \ No newline at end of file +<h2>memory_object_data_unlock</h2> +<hr> +<p> +<strong>Server Interface</strong> - Request that the memory manager change current access permission on the specified memory object's data. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_data_unlock</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>length</var>, + <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong> + + +<strong>kern_return_t seqnos_memory_object_data_unlock</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>length</var>, + <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_object</var> +<dd> +[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the abstract +memory object port. +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used for a response by the memory manager. If the memory +object has been supplied to more than one kernel, this parameter +identifies the kernel that is making the call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object. +<p> +<dt> <var>length</var> +<dd> +[in scalar] +The number of bytes to which the access applies, starting at +<var>offset</var>. The number converts to an integral number of memory object +pages. +<p> +<dt> <var>desired_access</var> +<dd> +[in scalar] +The memory access modes requested for the cached data. +Possible values are obtained by or'ing together the following values: +<dl> +<p> +<dt> <strong>VM_PROT_READ</strong> +<dd> +Allows read access. +<p> +<dt> <strong>VM_PROT_WRITE</strong> +<dd> +Allows write access. +<p> +<dt> <strong>VM_PROT_EXECUTE</strong> +<dd> +Allows execute access. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_data_unlock</strong> function is called as the +result of a kernel +message requesting the memory manager to permit at least the +desired access to the +specified data cached by the kernel. The memory manager is expected +to use the +<strong>memory_object_lock_request</strong> call in response. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>, +<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>, +<a href="memory_object_server.html"><strong>memory_object_server</strong></a>, +<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. diff --git a/osfmk/man/memory_object_destroy.html b/osfmk/man/memory_object_destroy.html index 8352832ee..b865a7a40 100755 --- a/osfmk/man/memory_object_destroy.html +++ b/osfmk/man/memory_object_destroy.html @@ -1 +1,53 @@ -<h2>memory_object_destroy</h2> <hr> <p> <strong>Function</strong> - Shut down a memory object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_destroy</strong> <strong>(memory_object_control_t</strong> <var>memory_control</var>, <strong>kern_return_t</strong> <var>reason</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used by the memory manager for cache management requests. This port is provided by the kernel in a <strong>memory_object_init</strong> call. <p> <dt> <var>reason</var> <dd> [in scalar] An error code indicating when the object must be destroyed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_destroy</strong> function tells the kernel to shut down the specified memory object. As a result of this call, the kernel no longer supports paging activity or any memory object calls on the memory object. The kernel issues a <strong>memory_object_terminate</strong> call to pass to the memory manager all rights to the memory object port and the memory control port. <p> To ensure that any modified cached data is returned before the object is terminated, the memory manager should call <strong>memory_object_lock_request</strong> with <var>should_flush</var> set and a lock value of <strong>VM_PROT_WRITE</strong> before it makes the <strong>memory_object_destroy</strong> call. <h3>NOTES</h3> <p> The <var>reason</var> code is currently ignored by the kernel. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>, <a href="memory_object_terminate.html"><strong>memory_object_terminate</strong></a>. \ No newline at end of file +<h2>memory_object_destroy</h2> +<hr> +<p> +<strong>Function</strong> - Shut down a memory object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_destroy</strong> + <strong>(memory_object_control_t</strong> <var>memory_control</var>, + <strong>kern_return_t</strong> <var>reason</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used by the memory manager for cache management requests. +This port is provided by the kernel in a <strong>memory_object_init</strong> call. +<p> +<dt> <var>reason</var> +<dd> +[in scalar] +An error code indicating when the object must be destroyed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_destroy</strong> function tells the kernel to shut down the +specified memory object. As a result of this call, the kernel +no longer supports +paging activity or any memory object calls on the memory object. +The kernel issues +a <strong>memory_object_terminate</strong> call to pass to the memory +manager all rights to +the memory object port and the memory control port. +<p> +To ensure that any modified cached data is returned before the object is +terminated, the memory manager should call <strong>memory_object_lock_request</strong> +with +<var>should_flush</var> set and a +lock value of <strong>VM_PROT_WRITE</strong> before it makes the +<strong>memory_object_destroy</strong> call. +<h3>NOTES</h3> +<p> +The <var>reason</var> code is currently ignored by the kernel. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>, +<a href="memory_object_terminate.html"><strong>memory_object_terminate</strong></a>. diff --git a/osfmk/man/memory_object_init.html b/osfmk/man/memory_object_init.html index 8ca621968..bdafa82b9 100755 --- a/osfmk/man/memory_object_init.html +++ b/osfmk/man/memory_object_init.html @@ -1 +1,76 @@ -<h2>memory_object_init</h2> <hr> <p> <strong>Server Interface</strong> - Initializes a memory object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_init</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>memory_object_control_t </strong><var>memory_control</var>, <strong>vm_size_t</strong> <var>memory_object_page_size</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_init</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_size_t</strong> <var>memory_object_page_size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>memory_object</var> <dd> [in abstract-memory-object port] The abstract memory object port that represents the memory object data, as supplied to the kernel in a vm_map call. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the abstract memory object port. <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control port] The memory cache control port to be used by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. <p> <dt> <var>memory_object_page_size</var> <dd> [in scalar] The page size used by the kernel. All calls involving this kernel must use data sizes that are integral multiples of this page size. </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_init</strong> function is called as the result of a kernel message notifying a memory manager that the kernel has been asked to map the specified memory object into a task's virtual address space. When asked to map a memory object for the first time, the kernel responds by making a <strong>memory_object_init</strong> call on the abstract memory object. This call is provided as a convenience to the memory manager, to allow it to initialize data structures and prepare to receive other requests. <p> In addition to the abstract memory object port itself, the call provides a memory cache control port that the memory manager can use to control use of its data by the kernel. The memory manager gets send rights for this port. <p> The kernel holds send rights for the abstract memory object port, and both send and receive rights for the memory cache control port. The call also supplies the virtual page size to be used for the memory mapping. The memory manager can use this size to detect mappings that use different data structures at initialization time, or to allocate buffers for use in reading data. <p> If a memory object is mapped into the address space of more than one task on different hosts (with independent kernels), the memory manager will receive a <strong>memory_object_init</strong> call from each kernel, containing a unique set of control and name ports. Note that each kernel may also use a different page size. <h3>RETURN VALUES</h3> <p> Any return value other than <strong>KERN_SUCCESS</strong> or <strong>MIG_NO_REPLY</strong>will cause <strong>mach_msg_server</strong> to remove the memory cache control reference. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_terminate.html"><strong>memory_object_terminate</strong></a>. \ No newline at end of file +<h2>memory_object_init</h2> +<hr> +<p> +<strong>Server Interface</strong> - Initializes a memory object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_init</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>memory_object_control_t </strong><var>memory_control</var>, + <strong>vm_size_t</strong> <var>memory_object_page_size</var><strong>);</strong> + + +<strong>kern_return_t seqnos_memory_object_init</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_size_t</strong> <var>memory_object_page_size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>memory_object</var> +<dd> +[in abstract-memory-object port] The abstract memory object port that represents the memory object data, as supplied to the kernel in a vm_map call. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] The sequence number of this message relative to the abstract memory object port. +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control port] The memory cache control port to be used by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. +<p> +<dt> <var>memory_object_page_size</var> +<dd> +[in scalar] The page size used by the kernel. All calls involving this kernel must use data sizes that are integral multiples of this page size. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_init</strong> function is called as the result +of a kernel message notifying a memory manager that the kernel has +been asked to map the specified memory object into a task's virtual +address space. When asked to map a memory object for the first time, +the kernel responds by making a <strong>memory_object_init</strong> +call on the abstract memory object. This call is provided as a +convenience to the memory manager, to allow it to initialize data +structures and prepare to receive other requests. +<p> +In addition to the +abstract memory object port itself, the call provides +a memory cache control port that the memory manager can use to +control use of its data by the kernel. The memory manager gets send +rights for this port. +<p> +The kernel holds send rights for the abstract memory object port, and +both send and receive rights for the memory cache control port. +The call also supplies the virtual page size to be used for +the memory mapping. The memory manager can use this size to detect +mappings that use different data structures at initialization time, or +to allocate buffers for use in reading data. +<p> +If a memory object is +mapped into the address space of more than one task on different hosts +(with independent kernels), the memory manager will receive a +<strong>memory_object_init</strong> call from each kernel, containing +a unique set of control and name ports. Note that each kernel may also +use a different page size. +<h3>RETURN VALUES</h3> +<p> + +Any return value other than <strong>KERN_SUCCESS</strong> +or <strong>MIG_NO_REPLY</strong>will cause +<strong>mach_msg_server</strong> to remove the memory cache control reference. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_terminate.html"><strong>memory_object_terminate</strong></a>. diff --git a/osfmk/man/memory_object_lock_request.html b/osfmk/man/memory_object_lock_request.html index 4adc569e2..4e8de055c 100755 --- a/osfmk/man/memory_object_lock_request.html +++ b/osfmk/man/memory_object_lock_request.html @@ -1 +1,173 @@ -<h2>memory_object_lock_request</h2> <hr> <p> <strong>Function</strong> - Restrict access to memory object data. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_lock_request</strong> <strong>(memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>memory_object_return_t</strong> <var>should_return</var>, <strong>boolean_t</strong> <var>should_flush</var>, <strong>vm_prot_t</strong> <var>lock_value</var>, <strong>mach_port_t</strong> <var>reply_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used by the memory manager for cache management requests. This port is provided by the kernel in a <strong>memory_object_init</strong> call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object, in bytes. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes of data (starting at <var>offset</var>) to be affected. The number must convert to an integral number of memory object pages. <p> <dt> <var>should_return</var> <dd> [in scalar] Clean indicator. Values are: <dl> <p> <dt> <strong>MEMORY_OBJECT_RETURN_NONE</strong> <dd> Don't return any pages. If <var>should_flush</var> is <strong>TRUE</strong>, pages will be discarded. <p> <dt> <strong>MEMORY_OBJECT_RETURN_DIRTY</strong> <dd> Return only dirty (modified) pages. If <var>should_flush</var> is <strong>TRUE</strong>, precious pages will be discarded; otherwise, the kernel maintains responsibility for precious pages. <p> <dt> <strong>MEMORY_OBJECT_RETURN_ALL</strong> <dd> Both dirty and precious pages are returned. If <var>should_flush</var> is <strong>FALSE</strong>, the kernel maintains responsibility for the precious pages. <p> <dt> <strong>MEMORY_OBJECT_RETURN_ANYTHING</strong> <dd> Any resident pages are returned. If <var>should_flush</var> is <strong>TRUE</strong>, precious pages will be discarded; otherwise, the kernel maintains responsibility for precious pages. </dl> <p> <dt> <var>should_flush</var> <dd> [in scalar] Flush indicator. If true, the kernel discards all pages within the range. <p> <dt> <var>lock_value</var> <dd> [in scalar] One or more forms of access <var>not</var> permitted for the specified data. Valid values are: <dl> <p> <dt> <strong>VM_PROT_NO_CHANGE</strong> <dd> Do not change the protection of any pages. <p> <dt> <strong>VM_PROT_NONE</strong> <dd> Prohibits no access (that is, all forms of access are permitted). <p> <dt> <strong>VM_PROT_READ</strong> <dd> Prohibits read access. <p> <dt> <strong>VM_PROT_WRITE</strong> <dd> Prohibits write access. <p> <dt> <strong>VM_PROT_EXECUTE</strong> <dd> Prohibits execute access. <p> <dt> <strong>VM_PROT_ALL</strong> <dd> Prohibits all forms of access. </dl> <p> <dt> <var>reply_port</var> <dd> [in reply receive (to be converted to send) right] The response port to be used by the kernel on a call to <strong>memory_object_lock_completed</strong>, or <strong>MACH_PORT_NULL</strong> if no response is required. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_lock_request</strong> function allows the memory manager to make the following requests of the kernel: <ul> <li> Clean the pages within the specified range by writing back all changed (that is, dirty) and precious pages. The kernel uses the <strong>memory_object_data_return</strong> call to write back the data. The <var>should_return</var> parameter must be set to non-zero. <p> <li> Flush all cached data within the specified range. The kernel invalidates the range of data and revokes all uses of that data. The <var>should_flush</var> parameter must be set to true. <p> <li> Alter access restrictions specified in the <strong>memory_object_data_supply</strong> call or a previous <strong>memory_object_lock_request</strong> call. The <var>lock_value</var> parameter must specify the new access restrictions. Note that this parameter can be used to unlock previously locked data. </ul> <p> Once the kernel performs all of the actions requested by this call, it issues a <strong>memory_object_lock_completed</strong> call using the <var>reply_to</var> port. <h3>NOTES</h3> <p> The <strong>memory_object_lock_request</strong> call affects only data that is cached at the time of the call. Access restrictions cannot be applied to pages for which data has not been provided. <p> When a running thread requires an access that is currently prohibited, the kernel issues a <strong>memory_object_data_unlock</strong> call specifying the access required. The memory manager can then use <strong>memory_object_lock_request</strong> to relax its access restrictions on the data. <p> To indicate that an unlock request is invalid (that is, requires permission that can never be granted), the memory manager must first flush the page. When the kernel requests the data again with the higher permission, the memory manager can indicate the error by responding with a call to <strong>memory_object_data_error</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>, <a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock</strong></a>, <a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>. \ No newline at end of file +<h2>memory_object_lock_request</h2> +<hr> +<p> +<strong>Function</strong> - Restrict access to memory object data. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_lock_request</strong> + <strong>(memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>memory_object_return_t</strong> <var>should_return</var>, + <strong>boolean_t</strong> <var>should_flush</var>, + <strong>vm_prot_t</strong> <var>lock_value</var>, + <strong>mach_port_t</strong> <var>reply_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used by the memory manager for cache management requests. +This port is provided by the kernel in a <strong>memory_object_init</strong> call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object, in bytes. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes of data (starting at <var>offset</var>) to be +affected. The number must convert to an integral number of memory object +pages. +<p> +<dt> <var>should_return</var> +<dd> +[in scalar] +Clean indicator. Values are: +<dl> +<p> +<dt> <strong>MEMORY_OBJECT_RETURN_NONE</strong> +<dd> +Don't return any pages. If <var>should_flush</var> is <strong>TRUE</strong>, pages will +be discarded. +<p> +<dt> <strong>MEMORY_OBJECT_RETURN_DIRTY</strong> +<dd> +Return only dirty (modified) pages. If <var>should_flush</var> is <strong>TRUE</strong>, +precious pages will be discarded; otherwise, the kernel +maintains responsibility for precious pages. +<p> +<dt> <strong>MEMORY_OBJECT_RETURN_ALL</strong> +<dd> +Both dirty and precious pages are returned. If <var>should_flush</var> is +<strong>FALSE</strong>, the kernel maintains responsibility for the precious +pages. +<p> +<dt> <strong>MEMORY_OBJECT_RETURN_ANYTHING</strong> +<dd> +Any resident pages are returned. If <var>should_flush</var> is <strong>TRUE</strong>, +precious pages will be discarded; otherwise, the kernel +maintains responsibility for precious pages. +</dl> +<p> +<dt> <var>should_flush</var> +<dd> +[in scalar] +Flush indicator. If true, the kernel discards all pages within +the range. +<p> +<dt> <var>lock_value</var> +<dd> +[in scalar] +One or more forms of access <var>not</var> permitted for the specified +data. Valid values are: +<dl> +<p> +<dt> <strong>VM_PROT_NO_CHANGE</strong> +<dd> +Do not change the protection of any pages. +<p> +<dt> <strong>VM_PROT_NONE</strong> +<dd> +Prohibits no access (that is, all forms of access are permitted). +<p> +<dt> <strong>VM_PROT_READ</strong> +<dd> +Prohibits read access. +<p> +<dt> <strong>VM_PROT_WRITE</strong> +<dd> +Prohibits write access. +<p> +<dt> <strong>VM_PROT_EXECUTE</strong> +<dd> +Prohibits execute access. +<p> +<dt> <strong>VM_PROT_ALL</strong> +<dd> +Prohibits all forms of access. +</dl> +<p> +<dt> <var>reply_port</var> +<dd> +[in reply receive (to be converted to send) right] +The response port to +be used by the kernel on a call to <strong>memory_object_lock_completed</strong>, +or <strong>MACH_PORT_NULL</strong> if no response is required. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_lock_request</strong> function allows the memory manager to +make the following requests of the kernel: +<ul> +<li> +Clean the pages within the specified range by writing back all changed (that +is, dirty) and precious pages. The kernel uses the +<strong>memory_object_data_return</strong> call to write back the data. +The <var>should_return</var> parameter must be set to +non-zero. + <p> +<li> +Flush all cached data within the specified range. The kernel invalidates the +range of data and revokes all uses of that data. The <var>should_flush</var> +parameter must be set to true. + <p> +<li> +Alter access restrictions specified in the <strong>memory_object_data_supply</strong> +call +or a previous <strong>memory_object_lock_request</strong> call. The +<var>lock_value</var> parameter +must specify the new access restrictions. Note that this parameter can be +used to unlock previously locked data. +</ul> +<p> +Once the kernel performs all of the actions requested by this +call, it issues a +<strong>memory_object_lock_completed</strong> call using the <var>reply_to</var> port. +<h3>NOTES</h3> +<p> +The <strong>memory_object_lock_request</strong> call affects only data +that is cached at the +time of the call. Access restrictions cannot be applied to pages +for which data +has not been provided. +<p> +When a running thread requires an access that is currently prohibited, +the kernel +issues a <strong>memory_object_data_unlock</strong> call specifying +the access required. The +memory manager can then use <strong>memory_object_lock_request</strong> to relax its +access restrictions on the data. +<p> +To indicate that an unlock request is invalid (that is, requires +permission that can +never be granted), the memory manager must first flush the page. When the +kernel requests the data again with the higher permission, the +memory manager can +indicate the error by responding with a call to +<strong>memory_object_data_error</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>, +<a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock</strong></a>, +<a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>. + diff --git a/osfmk/man/memory_object_perf_info.html b/osfmk/man/memory_object_perf_info.html index 4af60607f..cb0ec17b5 100755 --- a/osfmk/man/memory_object_perf_info.html +++ b/osfmk/man/memory_object_perf_info.html @@ -1 +1,53 @@ -<h2>memory_object_perf_info</h2> <hr> <p> <strong>Structure</strong> - Specifies a memory object's attributes with respect to performance. <h3>SYNOPSIS</h3> <pre> <strong>struct memory_object_perf_info</strong> <strong>{</strong> <strong>vm_offset_t</strong> <var>cluster_size</var><strong>;</strong> <strong>boolean_t</strong> <var>may_cache_object</var><strong>;</strong> <strong>};</strong> <strong>typedef struct memory_object_perf_info* memory_object_perf_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>cluster_size</var> <dd> Preferred cluster size (in bytes) for the memory object. This helps to determine how many pages are transferred in individual data request and return messages. <p> <dt> <var>may_cache_object</var> <dd> Cache indicator. If true, the kernel can cache data associated with the memory object (keep the memory object active) even if no virtual memory references to it remain. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_perf_info</strong> structure defines a memory object's character with respect to performance. <h3>NOTES</h3> <p> Sharing cached data among all the clients of a memory object can have a major impact on performance, especially if it can be extended across successive, as well as concurrent, uses. For example, the memory objects that represent program images can be used regularly by different programs. By retaining the data for these memory objects in cache, the number of secondary storage accesses can be reduced significantly. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>, <a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>, <a href="vm_region.html"><strong>vm_region</strong></a>, <a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>, <a href="VSD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>, <a href="vm_msync.html"><strong>vm_msync</strong></a>. <p> Structures: <a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>. \ No newline at end of file +<h2>memory_object_perf_info</h2> +<hr> +<p> +<strong>Structure</strong> - Specifies a memory object's attributes with respect to performance. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct memory_object_perf_info</strong> +<strong>{</strong> + <strong>vm_offset_t</strong> <var>cluster_size</var><strong>;</strong> + <strong>boolean_t</strong> <var>may_cache_object</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct memory_object_perf_info* memory_object_perf_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>cluster_size</var> +<dd> +Preferred cluster size (in bytes) for the memory object. This helps to +determine how many pages are transferred in individual data request +and return messages. +<p> +<dt> <var>may_cache_object</var> +<dd> +Cache indicator. If true, the kernel can cache data associated with the +memory object (keep the memory object active) even if no virtual +memory references to it remain. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_perf_info</strong> structure +defines a memory object's character with respect to performance. +<h3>NOTES</h3> +<p> +Sharing cached data among all the clients of a memory object can have a major +impact on performance, especially if it can be extended across successive, as +well as concurrent, uses. For example, the memory objects that represent +program images can be used regularly by different programs. +By retaining the data +for these memory objects in cache, the number of secondary storage accesses +can be reduced significantly. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>, +<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>, +<a href="vm_region.html"><strong>vm_region</strong></a>, +<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>, +<a href="VSD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>, +<a href="vm_msync.html"><strong>vm_msync</strong></a>. +<p> +Structures: +<a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>. diff --git a/osfmk/man/memory_object_server.html b/osfmk/man/memory_object_server.html index 7e10a7894..98cdd9848 100755 --- a/osfmk/man/memory_object_server.html +++ b/osfmk/man/memory_object_server.html @@ -1 +1,63 @@ -<h2>memory_object_server</h2> <hr> <p> <strong>Function</strong> - Handle kernel operation request aimed at a given memory manager. <h3>SYNOPSIS</h3> <pre> <strong>boolean_t memory_object_server</strong> <strong>(mach_msg_header_t</strong> <var>request_msg</var>, <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>in_msg</var> <dd> [pointer to in structure] The memory manager message received from the kernel. <p> <dt> <var>out_msg</var> <dd> [out structure] A reply message. No messages to a memory manager expect a direct reply, so this field is not used. </dl> <h3>DESCRIPTION</h3> <p> The <strong>memory_object_server</strong> function is the MIG generated server handling function to handle messages from the kernel targeted to a memory manager. <p> A \*Vmemory manager\*O is a server task that responds to specific messages from the kernel in order to handle memory management functions for the kernel. The <strong>memory_object_server</strong> function performs all necessary argument handling for a kernel message and calls one of the memory manager functions to interpret the message. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>TRUE</strong> <dd> The message was handled and the appropriate function was called. <p> <dt> <strong>FALSE</strong> <dd> The message did not apply to this memory management interface and no other action was taken. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="MO_default_server.html"><strong>memory_object_default_server<strong></a>, <a href="memory_object_data_request.html"><strong>memory_object_data_request<strong></a>, <a href="memory_object_data_return.html"><strong>memory_object_data_return<strong></a>, <a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock<strong></a>, <a href="MO_lock_completed.html"><strong>memory_object_lock_completed<strong></a>, <a href="MO_change_completed.html"><strong>memory_object_change_completed<strong></a>, <a href="MO_supply_completed.html"><strong>memory_object_supply_completed<strong></a>, <a href="memory_object_terminate.html"><strong>memory_object_terminate<strong></a>, <a href="memory_object_synchronize.html"><strong>memory_object_synchronize<strong></a>, <a href="SMO_server.html"><strong>seqnos_memory_object_server<strong></a>. \ No newline at end of file +<h2>memory_object_server</h2> +<hr> +<p> +<strong>Function</strong> - Handle kernel operation request aimed at a given memory manager. +<h3>SYNOPSIS</h3> +<pre> +<strong>boolean_t memory_object_server</strong> + <strong>(mach_msg_header_t</strong> <var>request_msg</var>, + <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>in_msg</var> +<dd> +[pointer to in structure] +The memory manager message received from +the kernel. +<p> +<dt> <var>out_msg</var> +<dd> +[out structure] +A reply message. No messages to a memory manager +expect a direct reply, so this field is not used. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>memory_object_server</strong> function is the MIG generated +server handling +function to handle messages from the kernel targeted to a memory manager. +<p> +A \*Vmemory manager\*O +is a server task that responds to specific messages from the +kernel in order to handle memory management functions for the kernel. The +<strong>memory_object_server</strong> function performs all necessary +argument handling for +a kernel message and calls one of the memory manager functions to interpret +the message. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The message was handled and the appropriate function was called. +<p> +<dt> <strong>FALSE</strong> +<dd> +The message did not apply to this memory management interface and +no other action was taken. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="MO_default_server.html"><strong>memory_object_default_server<strong></a>, +<a href="memory_object_data_request.html"><strong>memory_object_data_request<strong></a>, +<a href="memory_object_data_return.html"><strong>memory_object_data_return<strong></a>, +<a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock<strong></a>, +<a href="MO_lock_completed.html"><strong>memory_object_lock_completed<strong></a>, +<a href="MO_change_completed.html"><strong>memory_object_change_completed<strong></a>, +<a href="MO_supply_completed.html"><strong>memory_object_supply_completed<strong></a>, +<a href="memory_object_terminate.html"><strong>memory_object_terminate<strong></a>, +<a href="memory_object_synchronize.html"><strong>memory_object_synchronize<strong></a>, +<a href="SMO_server.html"><strong>seqnos_memory_object_server<strong></a>. diff --git a/osfmk/man/memory_object_synchronize.html b/osfmk/man/memory_object_synchronize.html index d446307a0..75cae0f37 100755 --- a/osfmk/man/memory_object_synchronize.html +++ b/osfmk/man/memory_object_synchronize.html @@ -1 +1,106 @@ -<h2>memory_object_synchronize</h2> <hr> <p> <strong>Server Interface</strong> - Forward a client's request to synchronize data with its image in backing store. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_synchronize</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_offset_t</strong> <var>length</var>, <strong>memory_object</strong> <var>sync_flags</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_synchronize</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_control_t</strong> <var>memory_control</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>vm_offset_t</strong> <var>length</var>, <strong>memory_object</strong> <var>sync_flags</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_object</var> <dd> [in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the abstract memory object port. <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control send right] The memory cache control port to be used for a response by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. <p> <dt> <var>offset</var> <dd> [in scalar] The offset within the memory object. <p> <dt> <var>length</var> <dd> [in scalar] The number of bytes cleaned or flushed, starting at <var>offset</var>. The number converts to an integral number of virtual pages. <p> <dt> <var>sync_flags</var> <dd> [in scalar] The bit-wise OR of flags affecting the synchronization. <dl> <p> <dt> <strong>VM_SYNC_INVALIDATE</strong> <dd> Flushes pages in the range. Only precious pages are returned to the memory manager. <p> <dt> <strong>VM_SYNC_SYNCHRONOUS</strong> <dd> Writes dirty and precious pages back to the memory manager, waits for pages to reach backing storage. <p> <dt> <strong>VM_SYNC_ASYNCHRONOUS</strong> <dd> Writes dirty and precious pages back to the memory manager, returns without waiting for pages to reach backing storage. </dl> </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_synchronize</strong> function is called as the result of a kernel message indicating that a client wishes to synchronize the contents of a range of a memory object with its backing storage image. This message would have been preceded by <strong>memory_object_data_return</strong> messages cleaning or flushing the specified range. <p> Depending on the client's supplied <var>sync_flags</var>, the manager waits for the pages to reach the desired state and then replies with <strong>memory_object_synchronize_completed</strong> at which time the client returns from its <strong>vm_msync</strong> call. Multiple synchronize requests may be outstanding at a time but they will not overlap. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_msync.html"><strong>vm_msync</strong></a>, <a href="MO_SY_completed.html"><strong>memory_object_synchronize_completed</strong></a>, <a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>, <a href="memory_object_server.html"><strong>memory_object_server</strong></a>, <a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. \ No newline at end of file +<h2>memory_object_synchronize</h2> +<hr> +<p> +<strong>Server Interface</strong> - Forward a client's request to synchronize data with its image in backing store. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_synchronize</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_offset_t</strong> <var>length</var>, + <strong>memory_object</strong> <var>sync_flags</var><strong>);</strong> + + +<strong>kern_return_t seqnos_memory_object_synchronize</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>vm_offset_t</strong> <var>length</var>, + <strong>memory_object</strong> <var>sync_flags</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_object</var> +<dd> +[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the abstract +memory object port. +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control send right] +The memory cache control port +to be used for a response by the memory manager. If the memory +object has been supplied to more than one kernel, this parameter +identifies the kernel that is making the call. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +The offset within the memory object. +<p> +<dt> <var>length</var> +<dd> +[in scalar] +The number of bytes cleaned or flushed, starting at <var>offset</var>. +The number converts to an integral number of virtual pages. +<p> +<dt> <var>sync_flags</var> +<dd> +[in scalar] +The bit-wise OR of flags affecting the synchronization. +<dl> +<p> +<dt> <strong>VM_SYNC_INVALIDATE</strong> +<dd> +Flushes pages in the range. Only precious pages are returned +to the memory manager. +<p> +<dt> <strong>VM_SYNC_SYNCHRONOUS</strong> +<dd> +Writes dirty and precious pages back to the memory manager, +waits for pages to reach backing storage. +<p> +<dt> <strong>VM_SYNC_ASYNCHRONOUS</strong> +<dd> +Writes dirty and precious pages back to the memory manager, +returns without waiting for pages to reach backing storage. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_synchronize</strong> function is called as the +result of a kernel +message indicating that a client wishes to synchronize the contents +of a range of a +memory object with its backing storage image. This message would have been +preceded by <strong>memory_object_data_return</strong> messages cleaning +or flushing the +specified range. +<p> +Depending on the client's supplied <var>sync_flags</var>, the manager waits +for the pages +to reach the desired state and then replies with +<strong>memory_object_synchronize_completed</strong> at which time the +client returns from its <strong>vm_msync</strong> call. Multiple +synchronize requests may be outstanding at a time but they will not overlap. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_msync.html"><strong>vm_msync</strong></a>, +<a href="MO_SY_completed.html"><strong>memory_object_synchronize_completed</strong></a>, +<a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>, +<a href="memory_object_server.html"><strong>memory_object_server</strong></a>, +<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. diff --git a/osfmk/man/memory_object_terminate.html b/osfmk/man/memory_object_terminate.html index a635d3331..24a19ab9f 100755 --- a/osfmk/man/memory_object_terminate.html +++ b/osfmk/man/memory_object_terminate.html @@ -1 +1,67 @@ -<h2>memory_object_terminate</h2> <hr> <p> <strong>Server Interface</strong> - Relinquish access to a memory object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t memory_object_terminate</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>memory_object_control_t</strong> <var>memory_control</var><strong>);</strong> <strong>kern_return_t seqnos_memory_object_terminate</strong> <strong>(memory_object_t</strong> <var>memory_object</var>, <strong>mach_port_seqno_t</strong> <var>seqno</var>, <strong>memory_object_control_t</strong> <var>memory_control</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>memory_object</var> <dd> [in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data. <p> <dt> <var>seqno</var> <dd> [in scalar] The sequence number of this message relative to the abstract memory object port. <p> <dt> <var>memory_control</var> <dd> [in memory-cache-control receive right] The memory cache control port to be used for a response by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call. </dl> <h3>DESCRIPTION</h3> <p> A <strong>memory_object_terminate</strong> function is called as the result of a kernel message notifying a memory manager that no mappings of the specified memory object remain. The kernel makes this call to allow the memory manager to clean up data structures associated with the deallocated mappings. The call provides receive rights to the memory cache control port so that the memory manager can retrieve any messages it sent into this port before knowing the memory object was being terminated and then destroy the port. The kernel also relinquishes its rights for all memory object ports. <p> The kernel terminates a memory object only after all address space mappings of the object have been deallocated, or upon explicit request by the memory manager. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_destroy.html"><strong>memory_object_destroy</strong></a>, <a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, <a href="memory_object_server.html"><strong>memory_object_server</strong></a>, <a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. \ No newline at end of file +<h2>memory_object_terminate</h2> +<hr> +<p> +<strong>Server Interface</strong> - Relinquish access to a memory object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t memory_object_terminate</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var><strong>);</strong> + + + +<strong>kern_return_t seqnos_memory_object_terminate</strong> + <strong>(memory_object_t</strong> <var>memory_object</var>, + <strong>mach_port_seqno_t</strong> <var>seqno</var>, + <strong>memory_object_control_t</strong> <var>memory_control</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>memory_object</var> +<dd> +[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data. +<p> +<dt> <var>seqno</var> +<dd> +[in scalar] +The sequence number of this message relative to the abstract +memory object port. +<p> +<dt> <var>memory_control</var> +<dd> +[in memory-cache-control receive right] +The memory cache control +port to be used for a response by the memory manager. If the memory +object has been supplied to more than one kernel, this parameter +identifies the kernel that is making the call. +</dl> +<h3>DESCRIPTION</h3> +<p> +A <strong>memory_object_terminate</strong> function is called as the +result of a kernel +message notifying a memory manager that no mappings of the specified memory +object remain. The kernel makes this call to allow the memory +manager to clean +up data structures associated with the deallocated mappings. +The call provides +receive rights to the memory cache control port so that the memory manager +can retrieve any messages it sent into this port before knowing the memory +object was being terminated and then destroy the port. The kernel also +relinquishes its rights for all memory object ports. +<p> +The kernel terminates a memory object only after all address space mappings of +the object have been deallocated, or upon explicit request by the memory +manager. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_destroy.html"><strong>memory_object_destroy</strong></a>, +<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, +<a href="memory_object_server.html"><strong>memory_object_server</strong></a>, +<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>. diff --git a/osfmk/man/norma_get_special_port.html b/osfmk/man/norma_get_special_port.html index 4a1416d7f..9641b66e5 100755 --- a/osfmk/man/norma_get_special_port.html +++ b/osfmk/man/norma_get_special_port.html @@ -1 +1,102 @@ -<h2>norma_get_special_port</h2> <hr> <p> <strong>Function</strong> - Acquire a send right for a specified node-specific special port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t norma_get_special_port</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>int</strong> <var>node</var>, <strong>int</strong> <var>which_port</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> </pre> <h4>Macro forms:</h4> <pre> <strong>#include<mach/norma_special_ports.h></strong> <strong>kern_return_t norma_get_device_port</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>int</strong> <var>node</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> <strong>kern_return_t norma_get_host_port</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>int</strong> <var>node</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> <strong>kern_return_t norma_get_host_priv_port</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>int</strong> <var>node</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> <strong>kern_return_t norma_get_nameserver_port</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>int</strong> <var>node</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>host_priv</var> <dd> [in host-control send right] The control port for the host for which to return the special port's send right. <p> <dt> <var>node</var> <dd> [in scalar] The index of the node for which the port is desired. <p> <dt> <var>which_port</var> <dd> [in scalar] The index of the special port for which the send right is requested. Valid values are: <dl> <p> <dt> <strong>NORMA_DEVICE_PORT</strong> <dd> [device-master send right] The device master port for the node. <p> <dt> <strong>NORMA_HOST_PORT</strong> <dd> [host-name send right] The host name port for the node. <p> <dt> <strong>NORMA_HOST_PRIV_PORT</strong> <dd> [host-control send right] The host control port for the node. <p> <dt> <strong>NORMA_NAMESERVER_PORT</strong> <dd> [name-server send right] The registered name server port for the node. </dl> <p> <dt> <var>special_port</var> <dd> [out norma-special send right] The returned value for the port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>norma_get_special_port</strong> function returns a send right for a special port belonging to <var>node</var> on <var>host_priv</var>. <p> Each node maintains a (small) set of node specific ports. The device master port, host name, and host control ports are maintained by the kernel. The kernel also permits a small set of server specified node specific ports; the name server port is an example and is given (by convention) an assigned special port index. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_host_self.html"><strong>mach_host_self</strong></a>, <a href="norma_set_special_port.html"><strong>norma_get_special_port</strong></a>, <a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>. \ No newline at end of file +<h2>norma_get_special_port</h2> +<hr> +<p> +<strong>Function</strong> - Acquire a send right for a specified node-specific special port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t norma_get_special_port</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>int</strong> <var>node</var>, + <strong>int</strong> <var>which_port</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + +</pre> +<h4>Macro forms:</h4> +<pre> + +<strong>#include<mach/norma_special_ports.h></strong> + +<strong>kern_return_t norma_get_device_port</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>int</strong> <var>node</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + +<strong>kern_return_t norma_get_host_port</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>int</strong> <var>node</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + +<strong>kern_return_t norma_get_host_priv_port</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>int</strong> <var>node</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + +<strong>kern_return_t norma_get_nameserver_port</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>int</strong> <var>node</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The control port for the host for which to +return the special port's send right. +<p> +<dt> <var>node</var> +<dd> +[in scalar] +The index of the node for which the port is desired. +<p> +<dt> <var>which_port</var> +<dd> +[in scalar] +The index of the special port for which the send right is +requested. Valid values are: + <dl> + <p> +<dt> <strong>NORMA_DEVICE_PORT</strong> +<dd> +[device-master send right] The device master port for the +node. +<p> +<dt> <strong>NORMA_HOST_PORT</strong> +<dd> +[host-name send right] The host name port for the node. +<p> +<dt> <strong>NORMA_HOST_PRIV_PORT</strong> +<dd> +[host-control send right] The host control port for the node. +<p> +<dt> <strong>NORMA_NAMESERVER_PORT</strong> +<dd> +[name-server send right] The registered name server port for +the node. +</dl> +<p> +<dt> <var>special_port</var> +<dd> +[out norma-special send right] +The returned value for the port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>norma_get_special_port</strong> function returns a send +right for a special port belonging to <var>node</var> on <var>host_priv</var>. +<p> +Each node maintains a (small) set of node specific ports. The device master +port, host name, and host control ports are +maintained by the kernel. The kernel also permits a small set +of server specified +node specific ports; the name server port is an example and is given (by +convention) an assigned special port index. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_host_self.html"><strong>mach_host_self</strong></a>, +<a href="norma_set_special_port.html"><strong>norma_get_special_port</strong></a>, +<a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>. diff --git a/osfmk/man/norma_node_self.html b/osfmk/man/norma_node_self.html index caa6cfae4..a41419cea 100755 --- a/osfmk/man/norma_node_self.html +++ b/osfmk/man/norma_node_self.html @@ -1 +1,32 @@ -<h2>norma_node_self</h2> <hr> <p> <strong>Function</strong> - Return the node index of the current host. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t norma_node_self</strong> <strong>(host_t</strong> <var>host</var>, <strong>int</strong> <var>int</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host</var> <dd> [in host send-right] Name of the host. <p> <dt> <var>node</var> <dd> [out scalar] Node index of the host. </dl> <h3>DESCRIPTION</h3> <p> The norma_node_self function returns the node index of the current host. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="norma_task_create.html"><strong>norma_task_create</strong></a>, <a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>, \ No newline at end of file +<h2>norma_node_self</h2> +<hr> +<p> +<strong>Function</strong> - Return the node index of the current host. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t norma_node_self</strong> + <strong>(host_t</strong> <var>host</var>, + <strong>int</strong> <var>int</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host</var> +<dd> +[in host send-right] Name of the host. +<p> +<dt> <var>node</var> +<dd> +[out scalar] Node index of the host. +</dl> +<h3>DESCRIPTION</h3> +<p> +The norma_node_self function returns the node index of the current host. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="norma_task_create.html"><strong>norma_task_create</strong></a>, +<a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>, diff --git a/osfmk/man/norma_port_location_hint.html b/osfmk/man/norma_port_location_hint.html index 99ecc9217..f4c899ca1 100755 --- a/osfmk/man/norma_port_location_hint.html +++ b/osfmk/man/norma_port_location_hint.html @@ -1 +1,44 @@ -<h2>norma_port_location_hint</h2> <hr> <p> <strong>Function</strong> - Guess a port's current location. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t norma_port_location_hint</strong> <strong>(task_t</strong> <var>task</var>, <strong>mach_port_t</strong> <var>name</var>, <strong>int</strong> <var>node</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] Task containing the right to locate <p> <dt> <var>name</var> <dd> [in scalar] Name of the right to locate <p> <dt> <var>node</var> <dd> [out scalar] Port location hint </dl> <h3>DESCRIPTION</h3> <p> The <strong>norma_port_location_hint</strong> function returns the best guess of <var>name</var>'s current location. The hint is guaranteed to be a node where the port once was; it is guaranteed to be accurate if port has never moved. This can be used to determine residence node for hosts, tasks, threads, etc. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="norma_task_create.html"><strong>norma_task_create</strong></a>. \ No newline at end of file +<h2>norma_port_location_hint</h2> +<hr> +<p> +<strong>Function</strong> - Guess a port's current location. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t norma_port_location_hint</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>mach_port_t</strong> <var>name</var>, + <strong>int</strong> <var>node</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +Task containing the right to locate +<p> +<dt> <var>name</var> +<dd> +[in scalar] +Name of the right to locate +<p> +<dt> <var>node</var> +<dd> +[out scalar] +Port location hint +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>norma_port_location_hint</strong> function returns the best +guess of <var>name</var>'s +current location. The hint is guaranteed to be a node where +the port once was; it is +guaranteed to be accurate if port has never moved. This can be used to +determine residence node for hosts, tasks, threads, etc. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="norma_task_create.html"><strong>norma_task_create</strong></a>. diff --git a/osfmk/man/norma_set_special_port.html b/osfmk/man/norma_set_special_port.html index 2624fe432..f2d1f381d 100755 --- a/osfmk/man/norma_set_special_port.html +++ b/osfmk/man/norma_set_special_port.html @@ -1 +1,97 @@ -<h2>norma_set_special_port</h2> <hr> <p> <strong>Function</strong> - Set node-specific special port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t norma_set_special_port</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>int</strong> <var>which_port</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> </pre> <h4>Macro forms:</h4> <pre> <strong>#include<mach/norma_special_ports.h></strong> <strong>kern_return_t norma_set_device_port</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> <strong>kern_return_t norma_set_host_port</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> <strong>kern_return_t norma_set_host_priv_port</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>int</strong> <var>node</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> <strong>kern_return_t norma_set_nameserver_port</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>host_priv</var> <dd> [in host-control send right] The host for which to set the special port. Currently, this must be the per-node host control port. <p> <dt> <var>node</var> <dd> [in scalar] The index of the node for which the port is to be set. <p> <dt> <var>which_port</var> <dd> [in scalar] The index of the special port to be set. Valid values are: <dl> <p> <dt> <strong>NORMA_DEVICE_PORT</strong> <dd> [device-master send right] The device master port for the node. <p> <dt> <strong>NORMA_HOST_PORT</strong> <dd> [host-name send right] The host name port for the node. <p> <dt> <strong>NORMA_HOST_PRIV_PORT</strong> <dd> [host-control send right] The host control port for the node. <p> <dt> <strong>NORMA_NAMESERVER_PORT</strong> <dd> [name-server send right] The registered name server port for the node. </dl> <p> <dt> <var>special_port</var> <dd> [in norma-special send right] Send right to the new special port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>norma_set_special_port</strong> function sets the special port belonging to <var>node</var> on <var>host_priv</var>. <p> Each node maintains a (small) set of node specific ports. The device master port, host name, and host control ports are maintained by the kernel. The kernel also permits a small set of server specified node specific ports; the name server port is an example and is given (by convention) an assigned special port index. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_host_self.html"><strong>mach_host_self</strong></a>, <a href="norma_get_special_port.html"><strong>norma_get_special_port</strong></a>. \ No newline at end of file +<h2>norma_set_special_port</h2> +<hr> +<p> +<strong>Function</strong> - Set node-specific special port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t norma_set_special_port</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>int</strong> <var>which_port</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + +</pre> +<h4>Macro forms:</h4> +<pre> + +<strong>#include<mach/norma_special_ports.h></strong> + +<strong>kern_return_t norma_set_device_port</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + +<strong>kern_return_t norma_set_host_port</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + +<strong>kern_return_t norma_set_host_priv_port</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>int</strong> <var>node</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + +<strong>kern_return_t norma_set_nameserver_port</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> +</pre> + +<h3>PARAMETERS</h3> +<dl> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The host for which to set the special port. +Currently, this must be the per-node host control port. +<p> +<dt> <var>node</var> +<dd> +[in scalar] +The index of the node for which the port is to be set. +<p> +<dt> <var>which_port</var> +<dd> +[in scalar] +The index of the special port to be set. Valid values are: +<dl> +<p> +<dt> <strong>NORMA_DEVICE_PORT</strong> +<dd> +[device-master send right] The device master port for the +node. +<p> +<dt> <strong>NORMA_HOST_PORT</strong> +<dd> +[host-name send right] The host name port for the node. +<p> +<dt> <strong>NORMA_HOST_PRIV_PORT</strong> +<dd> +[host-control send right] The host control port for the node. +<p> +<dt> <strong>NORMA_NAMESERVER_PORT</strong> +<dd> +[name-server send right] The registered name server port for +the node. +</dl> +<p> +<dt> <var>special_port</var> +<dd> +[in norma-special send right] +Send right to the new special port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>norma_set_special_port</strong> function sets the special +port belonging to <var>node</var> on <var>host_priv</var>. +<p> +Each node maintains a (small) set of node specific ports. The device master +port, host name, and host control ports are maintained by the kernel. +The kernel also permits +a small set of server specified +node specific ports; the name server port is an example and is given (by +convention) an assigned special port index. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_host_self.html"><strong>mach_host_self</strong></a>, +<a href="norma_get_special_port.html"><strong>norma_get_special_port</strong></a>. diff --git a/osfmk/man/norma_task_clone.html b/osfmk/man/norma_task_clone.html index 129835dab..737acb899 100755 --- a/osfmk/man/norma_task_clone.html +++ b/osfmk/man/norma_task_clone.html @@ -1 +1,78 @@ -<h2>norma_task_clone</h2> <hr> <p> <strong>Function</strong> - Create a remote task that shares access to parent task's memory regardless of inheritance attributes. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t norma_task_clone</strong> <strong>(task_t</strong> <var>parent_task</var>, <strong>boolean_t</strong> <var>inherit_memory</var>, <strong>int</strong> <var>child_node</var>, <strong>task_t</strong> <var>child_task</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>parent_task</var> <dd> [in task send right] The port for the task from which to draw the child task's port rights, resource limits, and address space. <p> <dt> <var>inherit_memory</var> <dd> [in scalar] Address space inheritance indicator. If true, the child task inherits the address space of the parent task. If false, the kernel assigns the child task an empty address space. <p> <dt> <var>child_node</var> <dd> [in scalar] The node index of the node on which to create the child. <p> <dt> <var>child_task</var> <dd> [out task send right] The kernel-assigned port name for the new task. </dl> <h3>DESCRIPTION</h3> <p> The <strong>norma_task_clone</strong> function "clones" a new task from <var>parent_task</var> on the specified <var>node</var> and returns the name of the new task in <var>child_task</var>. The child task acquires shared parts of the parent's address space (see <strong>vm_inherit</strong>) regardless of the inheritance set for the parent's memory regions, although the inheritance for the child's regions will be set to that of the parent's regions. The child task initially contains no threads. <p> By way of comparison, tasks created by the standard <strong>task_create</strong> primitive are created on the same node as the parent. <p> Other than being created on a different node, the new task has the same properties as if created by <strong>task_create</strong>. <h3>NOTES</h3> <p> This call differs from <strong>norma_task_create</strong> in that the inheritance set for the parent's memory regions is ignored; the child always shares memory with the parent. <p> This call is intended to support process migration, where the inheritance semantics of <strong>norma_task_create</strong> would break migrated programs that depended upon sharing relationships remaining after migration. <p> This call is not a true task migration call, in that it does not migrate the port space, threads, and other non-address-space attributes of the task. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="norma_task_create.html"><strong>norma_task_create</strong></a>. \ No newline at end of file +<h2>norma_task_clone</h2> +<hr> +<p> +<strong>Function</strong> - Create a remote task that shares access to parent task's memory regardless of inheritance attributes. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t norma_task_clone</strong> + <strong>(task_t</strong> <var>parent_task</var>, + <strong>boolean_t</strong> <var>inherit_memory</var>, + <strong>int</strong> <var>child_node</var>, + <strong>task_t</strong> <var>child_task</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>parent_task</var> +<dd> +[in task send right] +The port for the task from which to draw the child +task's port rights, resource limits, and address space. +<p> +<dt> <var>inherit_memory</var> +<dd> +[in scalar] +Address space inheritance indicator. If true, the child task +inherits the address space of the parent task. If false, the kernel assigns +the child task an empty address space. +<p> +<dt> <var>child_node</var> +<dd> +[in scalar] +The node index of the node on which to create the child. +<p> +<dt> <var>child_task</var> +<dd> +[out task send right] +The kernel-assigned port name for the new task. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>norma_task_clone</strong> function "clones" a new task from +<var>parent_task</var> on the specified <var>node</var> and returns the name +of the new task in <var>child_task</var>. The child +task acquires shared parts of the parent's +address space (see <strong>vm_inherit</strong>) +regardless of the inheritance set for the parent's memory regions, although the +inheritance for the child's regions will be set to that of the +parent's regions. The child +task initially contains no threads. +<p> +By way of comparison, tasks created by the standard <strong>task_create</strong> +primitive are created on the same node as the parent. +<p> +Other than being created on a different node, the new task has the same +properties as if created by <strong>task_create</strong>. +<h3>NOTES</h3> +<p> +This call differs from <strong>norma_task_create</strong> in that the +inheritance set for the +parent's memory regions is ignored; the child always shares memory with the +parent. +<p> +This call is intended to support process migration, where the inheritance +semantics of <strong>norma_task_create</strong> would break migrated +programs that depended upon +sharing relationships remaining after migration. +<p> +This call is not a true task migration call, in that it does +not migrate the port +space, threads, and other non-address-space attributes of the task. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="norma_task_create.html"><strong>norma_task_create</strong></a>. diff --git a/osfmk/man/norma_task_create.html b/osfmk/man/norma_task_create.html index 09e57be8e..68158d866 100755 --- a/osfmk/man/norma_task_create.html +++ b/osfmk/man/norma_task_create.html @@ -1 +1,59 @@ -<h2>norma_task_create</h2> <hr> <p> <strong>Function</strong> - Create a remote task using task_create semantics. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t norma_task_create</strong> <strong>(task_t</strong> <var>parent_task</var>, <strong>boolean_t</strong> <var>inherit_memory</var>, <strong>int</strong> <var>child_node</var>, <strong>task_t</strong> <var>child_task</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>parent_task</var> <dd> [in task send right] The port for the task from which to draw the child task's port rights, resource limits, and address space. <p> <dt> <var>inherit_memory</var> <dd> [in scalar] Address space inheritance indicator. If true, the child task inherits the address space of the parent task. If false, the kernel assigns the child task an empty address space. <p> <dt> <var>child_node</var> <dd> [in scalar] The node index of the node on which to create the child. <p> <dt> <var>child_task</var> <dd> [out task send right] The kernel-assigned port name for the new task. </dl> <h3>DESCRIPTION</h3> <p> The <strong>norma_task_create</strong> function creates a new task from <var>parent_task</var> on the specified <var>node</var> and returns the name of the new task in <var>child_task</var>. The child task acquires shared or copied parts of the parent's address space (see <strong>vm_inherit</strong>). The child task initially contains no threads. <p> By way of comparison, tasks created by the standard <strong>task_create</strong> primitive are created on the same node as the parent. <p> Other than being created on a different node, the new task has the same properties as if created by <strong>task_create</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>. \ No newline at end of file +<h2>norma_task_create</h2> +<hr> +<p> +<strong>Function</strong> - Create a remote task using task_create semantics. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t norma_task_create</strong> + <strong>(task_t</strong> <var>parent_task</var>, + <strong>boolean_t</strong> <var>inherit_memory</var>, + <strong>int</strong> <var>child_node</var>, + <strong>task_t</strong> <var>child_task</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>parent_task</var> +<dd> +[in task send right] +The port for the task from which to draw the child +task's port rights, resource limits, and address space. +<p> +<dt> <var>inherit_memory</var> +<dd> +[in scalar] +Address space inheritance indicator. If true, the child task +inherits the address space of the parent task. If false, the kernel assigns +the child task an empty address space. +<p> +<dt> <var>child_node</var> +<dd> +[in scalar] +The node index of the node on which to create the child. +<p> +<dt> <var>child_task</var> +<dd> +[out task send right] +The kernel-assigned port name for the new task. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>norma_task_create</strong> function creates a new task from +<var>parent_task</var> on the specified <var>node</var> and returns the name of the +new task in <var>child_task</var>. The child +task acquires shared or copied parts of the parent's address space (see +<strong>vm_inherit</strong>). The child task initially contains no threads. +<p> +By way of comparison, tasks created by the standard <strong>task_create</strong> +primitive are created on the same node as the parent. +<p> +Other than being created on a different node, the new task has the same +properties as if created by <strong>task_create</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>. diff --git a/osfmk/man/norma_task_teleport.html b/osfmk/man/norma_task_teleport.html index 698839391..102530ef1 100755 --- a/osfmk/man/norma_task_teleport.html +++ b/osfmk/man/norma_task_teleport.html @@ -1 +1,71 @@ -<h2>norma_task_teleport</h2> <hr> <p> <strong>Function</strong> - "Clone" a task on a specified node. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t norma_task_teleport</strong> <strong>(task_t</strong> <var>parent_task</var>, <strong>boolean_t</strong> <var>inherit_memory</var>, <strong>int</strong> <var>child_node</var>, <strong>task_t</strong> <var>child_task</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>parent_task</var> <dd> [in task send right] The port for the task from which to draw the child task's port rights, resource limits, and address space. <p> <dt> <var>inherit_memory</var> <dd> [in scalar] Address space inheritance indicator. If true, the child task in- herits the address space of the parent task. If false, the kernel assigns the child task an empty address space. <p> <dt> <var>child_node</var> <dd> [in scalar] The node index of the node on which to create the child. <p> <dt> <var>child_task</var> <dd> [out task send right] The kernel-assigned port name for the new task. </dl> <h3>DESCRIPTION</h3> <p> The norma_task_clone function "clones" a new task from parent_task on the specified node and returns the name of the new task in child_task. The child task acquires shared parts of the parent's address space (see vm_inherit) regardless of the inheritance set for the parent's memory regions, although the inheritance for the child's regions will be set to that of the parent's regions. The child task initially contains no threads. The parent_task is then terminated. By way of comparison, tasks created by the standard task_create primitive are created on the same node as the parent. Other than being created on a different node, the new task has the same properties as if created by task_create. <h3>NOTES</h3> <p> This call differs from norma_task_clone in that the parent task is terminated as part of the teleport call. This call differs from norma_task_create in that the inheritance set for the parent's memory regions is ignored; the child always shares memory with the parent. This call is intended to support process migration, where the inheritance semantics of norma_task_create would break migrated programs that depended upon sharing relationships remaining after migration. This call is not a true task migration call, in that it does not migrate the port space, threads, and other non-address-space attributes of the task. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>, <a href="task_create.html"><strong>task_create</strong></a>, <a href="norma_task_create.html"><strong>norma_task_create</strong></a>, \ No newline at end of file +<h2>norma_task_teleport</h2> +<hr> +<p> +<strong>Function</strong> - "Clone" a task on a specified node. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t norma_task_teleport</strong> + <strong>(task_t</strong> <var>parent_task</var>, + <strong>boolean_t</strong> <var>inherit_memory</var>, + <strong>int</strong> <var>child_node</var>, + <strong>task_t</strong> <var>child_task</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>parent_task</var> +<dd> +[in task send right] The port for the task from which to draw the child +task's port rights, resource limits, and address space. +<p> +<dt> <var>inherit_memory</var> +<dd> +[in scalar] Address space inheritance indicator. If true, the child task in- +herits the address space of the parent task. If false, the kernel assigns +the child task an empty address space. +<p> +<dt> <var>child_node</var> +<dd> +[in scalar] The node index of the node on which to create the child. +<p> +<dt> <var>child_task</var> +<dd> +[out task send right] The kernel-assigned port name for the new task. +</dl> +<h3>DESCRIPTION</h3> +<p> +The norma_task_clone function "clones" a new task from parent_task on +the specified node and returns the name of the new task in +child_task. The child task acquires shared parts of the parent's +address space (see vm_inherit) regardless of the inheritance set for +the parent's memory regions, although the inheritance for the +child's regions will be set to that of the parent's regions. The child +task initially contains no threads. The parent_task is then +terminated. +By way of comparison, tasks created by the standard task_create +primitive are created on the same node as the parent. +Other than being created on a different node, the new task has the +same properties as if created by task_create. +<h3>NOTES</h3> +<p> +This call differs from norma_task_clone in that the parent task is +terminated as part of the teleport call. +This call differs from norma_task_create in that the inheritance set +for the parent's memory regions is ignored; the child always shares +memory with the parent. +This call is intended to support process migration, where the +inheritance semantics of norma_task_create would break migrated +programs that depended upon sharing relationships remaining after +migration. +This call is not a true task migration call, in that it does not +migrate the port space, threads, and other non-address-space +attributes of the task. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>, +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="norma_task_create.html"><strong>norma_task_create</strong></a>, diff --git a/osfmk/man/notify_server.html b/osfmk/man/notify_server.html index 0984e5122..82986bdce 100755 --- a/osfmk/man/notify_server.html +++ b/osfmk/man/notify_server.html @@ -1 +1,54 @@ -<h2>notify_server</h2> <hr> <p> <strong>Function</strong> - Handle the next kernel-generated IPC notification. <h3>SYNOPSIS</h3> <pre> <strong>boolean_t notify_server</strong> <strong>(mach_msg_header_t</strong> <var>request_msg</var>, <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>in_msg</var> <dd> [pointer to in structure] The notification message received from the kernel. <p> <dt> <var>out_msg</var> <dd> [out structure] Not used. </dl> <h3>DESCRIPTION</h3> <p> The <strong>notify_server</strong> function is the MIG generated server handling function to handle messages from the kernel corresponding to IPC notifications. Such messages are delivered to the notification port named in a <strong>mach_msg</strong> or <strong>mach_port_request_notification</strong> call. The <strong>notify_server</strong> function performs all necessary argument handling for this kernel message and calls the appropriate handling function. These functions must be supplied by the caller. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>TRUE</strong> <dd> The message was handled and the appropriate function was called. <p> <dt> <strong>FALSE</strong> <dd> The message did not apply to the notification mechanism and no other action was taken. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="seqnos_notify_server.html"><strong>seqnos_notify_server<strong></a>, <a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name<strong></a>, <a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders<strong></a>, <a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted<strong></a>, <a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once<strong></a>. \ No newline at end of file +<h2>notify_server</h2> +<hr> +<p> +<strong>Function</strong> - Handle the next kernel-generated IPC notification. +<h3>SYNOPSIS</h3> +<pre> +<strong>boolean_t notify_server</strong> + <strong>(mach_msg_header_t</strong> <var>request_msg</var>, + <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>in_msg</var> +<dd> +[pointer to in structure] +The notification message received from the +kernel. +<p> +<dt> <var>out_msg</var> +<dd> +[out structure] +Not used. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>notify_server</strong> function is the MIG generated server +handling function to +handle messages from the kernel corresponding to IPC notifications. Such +messages are delivered to the notification port named in a <strong>mach_msg</strong> +or <strong>mach_port_request_notification</strong> call. The <strong>notify_server</strong> +function performs all necessary +argument handling for this kernel message and calls the appropriate handling +function. These functions must be supplied by the caller. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The message was handled and the appropriate function was called. +<p> +<dt> <strong>FALSE</strong> +<dd> +The message did not apply to the notification mechanism and no other +action was taken. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="seqnos_notify_server.html"><strong>seqnos_notify_server<strong></a>, +<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name<strong></a>, +<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders<strong></a>, +<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted<strong></a>, +<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once<strong></a>. diff --git a/osfmk/man/policy_fifo_info.html b/osfmk/man/policy_fifo_info.html index 2e8acea7e..32ba90c61 100755 --- a/osfmk/man/policy_fifo_info.html +++ b/osfmk/man/policy_fifo_info.html @@ -1 +1,75 @@ -<h2>policy_fifo_info</h2> <hr> <p> <strong>Structure</strong> - Specifies information associated with the system's First-In-First-Out scheduling policy. <h3>SYNOPSIS</h3> <pre> <strong>struct policy_fifo_limit</strong> <strong>{</strong> <strong>int</strong> <var>max_priority</var><strong>;</strong> <strong>};</strong> <strong>struct policy_fifo_base</strong> <strong>{</strong> <strong>int</strong> <var>base_priority</var><strong>;</strong> <strong>};</strong> <strong>struct policy_fifo_info</strong> <strong>{</strong> <strong>int</strong> <var>max_priority</var><strong>;</strong> <strong>int</strong> <var>base_priority</var><strong>;</strong> <strong>boolean_t</strong> <var>depressed</var><strong>;</strong> <strong>int</strong> <var>depress_priority</var><strong>;</strong> <strong>};</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>max_priority</var> <dd> Maximum scheduling priority <p> <dt> <var>base_priority</var> <dd> Scheduling priority <p> <dt> <var>depressed</var> <dd> True if scheduling priority is depressed <p> <dt> <var>depress_priority</var> <dd> Scheduling priority from which depressed </dl> <h3>DESCRIPTION</h3> <p> The <strong>policy_fifo_info</strong> structure defines the first-in-first-out scheduling policy information. FIFO threads have two priorities associated with them by the system: <ul> <p> <li> A maximum priority value which can be raised only via privileged operation so that users may not unfairly compete with other users in their processor set. Newly created threads obtain their maximum priority from that of their assigned processor set. <p> <li> A priority value which can be set by the thread to any value up to a maximum priority. Newly created threads obtain their priority from their task. </ul> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="task_info.html"><strong>task_info</strong></a>, <a href="processor_set_info.html"><strong>processor_set_info</strong></a>, <a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, <a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>, <a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>, <a href="task_policy.html"><strong>task_policy</strong></a>, <a href="thread_policy.html"><strong>thread_policy</strong></a>, <a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>. <p> Data Structures: <a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, <a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. \ No newline at end of file +<h2>policy_fifo_info</h2> +<hr> +<p> +<strong>Structure</strong> - Specifies information associated with the system's First-In-First-Out scheduling policy. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct policy_fifo_limit</strong> +<strong>{</strong> + <strong>int</strong> <var>max_priority</var><strong>;</strong> +<strong>};</strong> + +<strong>struct policy_fifo_base</strong> +<strong>{</strong> + <strong>int</strong> <var>base_priority</var><strong>;</strong> +<strong>};</strong> + +<strong>struct policy_fifo_info</strong> +<strong>{</strong> + <strong>int</strong> <var>max_priority</var><strong>;</strong> + <strong>int</strong> <var>base_priority</var><strong>;</strong> + <strong>boolean_t</strong> <var>depressed</var><strong>;</strong> + <strong>int</strong> <var>depress_priority</var><strong>;</strong> +<strong>};</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>max_priority</var> +<dd> +Maximum scheduling priority +<p> +<dt> <var>base_priority</var> +<dd> +Scheduling priority +<p> +<dt> <var>depressed</var> +<dd> +True if scheduling priority is depressed +<p> +<dt> <var>depress_priority</var> +<dd> +Scheduling priority from which depressed +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>policy_fifo_info</strong> structure defines the first-in-first-out +scheduling policy information. +FIFO threads have two priorities associated with them by the system: +<ul> + <p> +<li> +A maximum priority value which can be raised only via privileged operation +so that users may not unfairly compete with other users in their processor +set. Newly created threads obtain their maximum priority from that of their +assigned processor set. + <p> +<li> +A priority value which can be set by the thread to any value up to a +maximum priority. Newly created threads obtain their priority from their task. +</ul> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="processor_set_info.html"><strong>processor_set_info</strong></a>, +<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, +<a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>, +<a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>, +<a href="task_policy.html"><strong>task_policy</strong></a>, +<a href="thread_policy.html"><strong>thread_policy</strong></a>, +<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>. +<p> +Data Structures: +<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, +<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. diff --git a/osfmk/man/policy_rr_info.html b/osfmk/man/policy_rr_info.html index a1c44df58..c6e5b9a88 100755 --- a/osfmk/man/policy_rr_info.html +++ b/osfmk/man/policy_rr_info.html @@ -1 +1,81 @@ -<h2>policy_rr_info</h2> <hr> <p> <strong>Structure</strong> - Specifies information associated with the system's Round Robin scheduling policy. <h3>SYNOPSIS</h3> <pre> <strong>struct policy_rr_limit</strong> <strong>{</strong> <strong>int</strong> <var>max_priority</var><strong>;</strong> <strong>};</strong> <strong>struct policy_rr_base</strong> <strong>{</strong> <strong>int</strong> <var>base_priority</var><strong>;</strong> <strong>int</strong> <var>quantum</var><strong>;</strong> <strong>};</strong> <strong>struct policy_rr_info</strong> <strong>{</strong> <strong>int</strong> <var>max_priority</var><strong>;</strong> <strong>int</strong> <var>base_priority</var><strong>;</strong> <strong>int</strong> <var>quantum</var><strong>;</strong> <strong>boolean_t</strong> <var>depressed</var><strong>;</strong> <strong>int</strong> <var>depress_priority</var><strong>;</strong> <strong>};</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>max_priority</var> <dd> Maximum scheduling priority <p> <dt> <var>base_priority</var> <dd> Scheduling priority <p> <dt> <var>quantum</var> <dd> Scheduling quantum (in milliseconds) <p> <dt> <var>depressed</var> <dd> True if scheduling priority is depressed <p> <dt> <var>depress_priority</var> <dd> Scheduling priority from which depressed </dl> <h3>DESCRIPTION</h3> <p> The <strong>policy_rr_info</strong> structure defines the round-robin scheduling policy information. Round-robin threads have two priorities associated with them by the system: <ul> <p> <li> A maximum priority value which can be raised only via privileged operation so that users may not unfairly compete with other users in their processor set. Newly created threads obtain their maximum priority from that of their assigned processor set. <p> <li> A priority value which can be set by the thread to any value up to a maximum priority. Newly created threads obtain their priority from their task. </ul> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="task_info.html"><strong>task_info</strong></a>, <a href="processor_set_info.html"><strong>processor_set_info</strong></a>, <a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, <a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>, <a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>, <a href="task_policy.html"><strong>task_policy</strong></a>, <a href="thread_policy.html"><strong>thread_policy</strong></a>, <a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>. <p> Data Structures: <a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, <a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. \ No newline at end of file +<h2>policy_rr_info</h2> +<hr> +<p> +<strong>Structure</strong> - Specifies information associated with the system's Round Robin scheduling policy. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct policy_rr_limit</strong> +<strong>{</strong> + <strong>int</strong> <var>max_priority</var><strong>;</strong> +<strong>};</strong> + +<strong>struct policy_rr_base</strong> +<strong>{</strong> + <strong>int</strong> <var>base_priority</var><strong>;</strong> + <strong>int</strong> <var>quantum</var><strong>;</strong> +<strong>};</strong> + +<strong>struct policy_rr_info</strong> +<strong>{</strong> + <strong>int</strong> <var>max_priority</var><strong>;</strong> + <strong>int</strong> <var>base_priority</var><strong>;</strong> + <strong>int</strong> <var>quantum</var><strong>;</strong> + <strong>boolean_t</strong> <var>depressed</var><strong>;</strong> + <strong>int</strong> <var>depress_priority</var><strong>;</strong> +<strong>};</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>max_priority</var> +<dd> +Maximum scheduling priority +<p> +<dt> <var>base_priority</var> +<dd> +Scheduling priority +<p> +<dt> <var>quantum</var> +<dd> +Scheduling quantum (in milliseconds) +<p> +<dt> <var>depressed</var> +<dd> +True if scheduling priority is depressed +<p> +<dt> <var>depress_priority</var> +<dd> +Scheduling priority from which depressed +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>policy_rr_info</strong> structure defines the round-robin +scheduling policy information. +Round-robin threads have two priorities associated with them by the system: +<ul> + <p> +<li> +A maximum priority value which can be raised only via privileged operation +so that users may not unfairly compete with other users in their processor +set. Newly created threads obtain their maximum priority from that of their +assigned processor set. + <p> +<li> +A priority value which can be set by the thread to any value up to a +maximum priority. Newly created threads obtain their priority from their task. +</ul> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="processor_set_info.html"><strong>processor_set_info</strong></a>, +<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, +<a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>, +<a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>, +<a href="task_policy.html"><strong>task_policy</strong></a>, +<a href="thread_policy.html"><strong>thread_policy</strong></a>, +<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>. +<p> +Data Structures: +<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, +<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. diff --git a/osfmk/man/policy_timeshare_info.html b/osfmk/man/policy_timeshare_info.html index 6682c025b..2295ba1dc 100755 --- a/osfmk/man/policy_timeshare_info.html +++ b/osfmk/man/policy_timeshare_info.html @@ -1 +1,88 @@ -<h2>policy_timeshare_info</h2> <hr> <p> <strong>Structure</strong> - Specifies information associated with the system's Timeshare scheduling policy. <h3>SYNOPSIS</h3> <pre> <strong>struct policy_timeshare_limit</strong> <strong>{</strong> <strong>int</strong> <var>max_priority</var><strong>;</strong> <strong>};</strong> <strong>struct policy_timeshare_base</strong> <strong>{</strong> <strong>int</strong> <var>base_priority</var><strong>;</strong> <strong>};</strong> <strong>struct policy_timeshare_info</strong> <strong>{</strong> <strong>int</strong> <var>max_priority</var><strong>;</strong> <strong>int</strong> <var>base_priority</var><strong>;</strong> <strong>int</strong> <var>cur_priority</var><strong>;</strong> <strong>boolean_t</strong> <var>depressed</var><strong>;</strong> <strong>int</strong> <var>depress_priority</var><strong>;</strong> <strong>};</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>max_priority</var> <dd> Maximum scheduling priority. <p> <dt> <var>base_priority</var> <dd> Base scheduling priority. <p> <dt> <var>cur_priority</var> <dd> Current scheduling priority. <p> <dt> <var>depressed</var> <dd> True if scheduling priority is depressed. <p> <dt> <var>depress_priority</var> <dd> Scheduling priority from which depressed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>policy_timeshare_info</strong> structure defines the timeshare scheduling policy information. Timeshare threads have three priorities associated with them by the system: <ul> <p> <li> A maximum priority value which can be raised only via privileged operation so that users may not unfairly compete with other users in their processor set. Newly created threads obtain their maximum priority from that of their assigned processor set. <p> <li> A priority value which can be set by the thread to any value up to a maximum priority. Newly created threads obtain their priority from their task. <p> <li> A scheduled priority value which is used to make scheduling decisions for the thread. This value is determined on the basis of the user priority value by the scheduling policy (for time-sharing, this means adding an increment derived from CPU usage). </ul> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="task_info.html"><strong>task_info</strong></a>, <a href="processor_set_info.html"><strong>processor_set_info</strong></a>, <a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, <a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>, <a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>, <a href="task_policy.html"><strong>task_policy</strong></a>, <a href="thread_policy.html"><strong>thread_policy</strong></a>, <a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>. <p> Data Structures: <a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, <a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>. \ No newline at end of file +<h2>policy_timeshare_info</h2> +<hr> +<p> +<strong>Structure</strong> - Specifies information associated with the system's Timeshare scheduling policy. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct policy_timeshare_limit</strong> +<strong>{</strong> + <strong>int</strong> <var>max_priority</var><strong>;</strong> +<strong>};</strong> + +<strong>struct policy_timeshare_base</strong> +<strong>{</strong> + <strong>int</strong> <var>base_priority</var><strong>;</strong> +<strong>};</strong> + +<strong>struct policy_timeshare_info</strong> +<strong>{</strong> + <strong>int</strong> <var>max_priority</var><strong>;</strong> + <strong>int</strong> <var>base_priority</var><strong>;</strong> + <strong>int</strong> <var>cur_priority</var><strong>;</strong> + <strong>boolean_t</strong> <var>depressed</var><strong>;</strong> + <strong>int</strong> <var>depress_priority</var><strong>;</strong> +<strong>};</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>max_priority</var> +<dd> +Maximum scheduling priority. +<p> +<dt> <var>base_priority</var> +<dd> +Base scheduling priority. +<p> +<dt> <var>cur_priority</var> +<dd> +Current scheduling priority. +<p> +<dt> <var>depressed</var> +<dd> +True if scheduling priority is depressed. +<p> +<dt> <var>depress_priority</var> +<dd> +Scheduling priority from which depressed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>policy_timeshare_info</strong> structure defines the timeshare +scheduling policy +information. +Timeshare threads have three priorities associated with them by the system: +<ul> + <p> +<li> +A maximum priority value which can be raised only via privileged operation +so that users may not unfairly compete with other users in their processor +set. Newly created threads obtain their maximum priority from that of their +assigned processor set. + <p> +<li> +A priority value which can be set by the thread to any value up to a +maximum priority. Newly created threads obtain their priority from their task. + <p> +<li> +A scheduled priority value which is used to make scheduling decisions for +the thread. This value is determined on the basis of the user +priority value by +the scheduling policy (for time-sharing, this means adding an increment +derived from CPU usage). +</ul> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="processor_set_info.html"><strong>processor_set_info</strong></a>, +<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, +<a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>, +<a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>, +<a href="task_policy.html"><strong>task_policy</strong></a>, +<a href="thread_policy.html"><strong>thread_policy</strong></a>, +<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>. +<p> +Data Structures: +<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, +<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>. diff --git a/osfmk/man/processor_assign.html b/osfmk/man/processor_assign.html index 61e07d89c..6dddefd72 100755 --- a/osfmk/man/processor_assign.html +++ b/osfmk/man/processor_assign.html @@ -1 +1,59 @@ -<h2>processor_assign</h2> <hr> <p> <strong>Function</strong> - Assign a processor to a processor set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_assign</strong> <strong>(processor_t</strong> <var>processor</var>, <strong>processor_set_t</strong> <var>new_set</var>, <strong>boolean_t</strong> <var>wait</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor</var> <dd> [in processor send right] The processor to be assigned. <dt> <var>new_set</var> <dd> [in processor-set-control send right] The control port for the processor set into which the processor is to be assigned. <dt> <var>wait</var> <dd> [in scalar] True if the call should wait for the completion of the assignment. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_assign</strong> function assigns <var>processor</var> to the set <var>new_set</var>. After the assignment is completed, the processor only executes threads that are assigned to that processor set. Any previous assignment of the processor is nullified. The master processor cannot be re-assigned. <p> The <var>wait</var> argument indicates whether the caller should wait for the assignment to be completed or should return immediately. Dedicated kernel threads are used to perform processor assignment, so setting <var>wait</var> to <strong>FALSE</strong> allows assignment requests to be queued and performed more quickly, especially if the kernel has more than one dedicated internal thread for processor assignment. <p> All processors take clock interrupts at all times. Redirection of other device interrupts away from processors assigned to other than the default processor set is machine dependent. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_create.html">processor_set_create</a>, <a href="processor_set_info.html">processor_set_info</a>, <a href="task_assign.html">task_assign</a>, <a href="thread_assign.html">thread_assign</a>. \ No newline at end of file +<h2>processor_assign</h2> +<hr> +<p> +<strong>Function</strong> - Assign a processor to a processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_assign</strong> + <strong>(processor_t</strong> <var>processor</var>, + <strong>processor_set_t</strong> <var>new_set</var>, + <strong>boolean_t</strong> <var>wait</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor</var> +<dd> +[in processor send right] +The processor to be assigned. +<dt> <var>new_set</var> +<dd> +[in processor-set-control send right] +The control port for the processor +set into which the processor is to be assigned. +<dt> <var>wait</var> +<dd> +[in scalar] +True if the call should wait for the completion of the +assignment. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_assign</strong> function assigns <var>processor</var> to +the set <var>new_set</var>. After the +assignment is completed, the processor only executes threads that are assigned +to that processor set. Any previous assignment of the processor +is nullified. The +master processor cannot be re-assigned. +<p> +The <var>wait</var> argument indicates whether the +caller should wait for the assignment +to be completed or should return immediately. Dedicated kernel threads are +used to perform processor assignment, so setting <var>wait</var> to <strong>FALSE</strong> allows +assignment requests to be queued and performed more quickly, especially +if the kernel has +more than one dedicated internal thread for processor assignment. +<p> +All processors take clock interrupts at all times. Redirection of other device +interrupts away from processors assigned to other than the default +processor set is +machine dependent. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_create.html">processor_set_create</a>, +<a href="processor_set_info.html">processor_set_info</a>, +<a href="task_assign.html">task_assign</a>, +<a href="thread_assign.html">thread_assign</a>. diff --git a/osfmk/man/processor_basic_info.html b/osfmk/man/processor_basic_info.html index aa0a0395d..e49220bf2 100755 --- a/osfmk/man/processor_basic_info.html +++ b/osfmk/man/processor_basic_info.html @@ -1 +1,47 @@ -<h2>processor_basic_info</h2> <hr> <p> <strong>Structure</strong> - Defines the basic information about a processor. <h3>SYNOPSIS</h3> <pre> <strong>struct processor_basic_info</strong> <strong>{</strong> <strong>cpu_type_t</strong> <var>cpu_type</var><strong>;</strong> <strong>cpu_subtype_t</strong> <var>cpu_subtype</var><strong>;</strong> <strong>boolean_t</strong> <var>running</var><strong>;</strong> <strong>int</strong> <var>slot_num</var><strong>;</strong> <strong>boolean_t</strong> <var>is_master</var><strong>;</strong> <strong>};</strong> <strong>typedef struct processor_basic_info* processor_basic_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>cpu_type</var> <dd> Type of CPU <p> <dt> <var>cpu_subtype</var> <dd> Sub-type of CPU <p> <dt> <var>running</var> <dd> True if the CPU is running <p> <dt> <var>slot_num</var> <dd> Slot number of the CPU <p> <dt> <var>is_master</var> <dd> True if this is the master processor </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_basic_info</strong> structure defines the information available about a processor slot. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_info.html"><strong>processor_info</strong></a>. \ No newline at end of file +<h2>processor_basic_info</h2> +<hr> +<p> +<strong>Structure</strong> - Defines the basic information about a processor. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct processor_basic_info</strong> +<strong>{</strong> + <strong>cpu_type_t</strong> <var>cpu_type</var><strong>;</strong> + <strong>cpu_subtype_t</strong> <var>cpu_subtype</var><strong>;</strong> + <strong>boolean_t</strong> <var>running</var><strong>;</strong> + <strong>int</strong> <var>slot_num</var><strong>;</strong> + <strong>boolean_t</strong> <var>is_master</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct processor_basic_info* processor_basic_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>cpu_type</var> +<dd> +Type of CPU +<p> +<dt> <var>cpu_subtype</var> +<dd> +Sub-type of CPU +<p> +<dt> <var>running</var> +<dd> +True if the CPU is running +<p> +<dt> <var>slot_num</var> +<dd> +Slot number of the CPU +<p> +<dt> <var>is_master</var> +<dd> +True if this is the master processor +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_basic_info</strong> structure defines the information +available about a processor slot. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_info.html"><strong>processor_info</strong></a>. diff --git a/osfmk/man/processor_control.html b/osfmk/man/processor_control.html index faa83aabd..034bc2fda 100755 --- a/osfmk/man/processor_control.html +++ b/osfmk/man/processor_control.html @@ -1 +1,51 @@ -<h2>processor_control</h2> <hr> <p> <strong>Function</strong> - Perform caller-specified operation on target processor. (Protected Interface.) <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_control</strong> <strong>(processor_t</strong> <var>processor</var>, <strong>processor_info_t</strong> <var>cmd</var>, <strong>mach_msg_type_number_t*</strong> <var>count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor</var> <dd> [in processor send right] The processor to be controlled. <dt> <var>cmd</var> <dd> [pointer to in array of natural-sized units] An array containing the command to be applied to the processor. <dt> <var>count</var> <dd> [in scalar] The size of the <var>cmd</var> array (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_control</strong> function allows privileged software to control a processor in a multi-processor that so allows it. The interpretation of <var>cmd</var> is machine dependent. <h3>NOTES</h3> <p> These operations are machine dependent. They may do nothing. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_FAILURE</strong> <dd> The operation was not performed. A likely reason is that it is not supported on this processor. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_start.html">processor_start</a>, <a href="processor_exit.html">processor_exit</a>, <a href="processor_info.html">processor_info</a>, <a href="host_processors.html">host_processors</a>. \ No newline at end of file +<h2>processor_control</h2> +<hr> +<p> +<strong>Function</strong> - Perform caller-specified operation on target processor. (Protected Interface.) +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_control</strong> + <strong>(processor_t</strong> <var>processor</var>, + <strong>processor_info_t</strong> <var>cmd</var>, + <strong>mach_msg_type_number_t*</strong> <var>count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor</var> +<dd> +[in processor send right] +The processor to be controlled. +<dt> <var>cmd</var> +<dd> +[pointer to in array of natural-sized units] +An array containing the +command to be applied to the processor. +<dt> <var>count</var> +<dd> +[in scalar] +The size of the <var>cmd</var> array (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_control</strong> function allows privileged software +to control a +processor in a multi-processor that so allows it. The interpretation +of <var>cmd</var> is machine +dependent. +<h3>NOTES</h3> +<p> +These operations are machine dependent. They may do nothing. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>KERN_FAILURE</strong> +<dd> +The operation was not performed. A likely reason is that it +is not supported on this processor. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_start.html">processor_start</a>, +<a href="processor_exit.html">processor_exit</a>, +<a href="processor_info.html">processor_info</a>, +<a href="host_processors.html">host_processors</a>. diff --git a/osfmk/man/processor_exit.html b/osfmk/man/processor_exit.html index 0e8cd75e7..e791fd561 100755 --- a/osfmk/man/processor_exit.html +++ b/osfmk/man/processor_exit.html @@ -1 +1,44 @@ -<h2>processor_exit</h2> <hr> <p> <strong>Function</strong> - Exit a processor. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_exit</strong> <strong>(processor_t</strong> <var>processor</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor</var> <dd> [in processor send right] The processor to be controlled. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_exit</strong> function allows privileged software to exit a processor in a multi-processor that so allows it. An exited processor is removed from the processor set to which it was assigned and ceases to be active. The interpretation of this operation is machine dependent. <h3>NOTES</h3> <p> This operation is machine dependent. It may do nothing. <h3>CAUTIONS</h3> <p> The ability to restart an exited processor is machine dependent. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_FAILURE</strong> <dd> The operation was not performed. A likely reason is that it is not supported on this processor. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_control.html">processor_control</a>, <a href="processor_start.html">processor_start</a>, <a href="processor_info.html">processor_info</a>, <a href="host_processors.html">host_processors</a>. \ No newline at end of file +<h2>processor_exit</h2> +<hr> +<p> +<strong>Function</strong> - Exit a processor. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_exit</strong> + <strong>(processor_t</strong> <var>processor</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor</var> +<dd> +[in processor send right] +The processor to be controlled. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_exit</strong> function allows privileged software +to exit a processor in a +multi-processor that so allows it. An exited processor is removed from the +processor set to which it was assigned and ceases to be active. +The interpretation of +this operation is machine dependent. +<h3>NOTES</h3> +<p> +This operation is machine dependent. It may do nothing. +<h3>CAUTIONS</h3> +<p> +The ability to restart an exited processor is machine dependent. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>KERN_FAILURE</strong> +<dd> +The operation was not performed. A likely reason is that it +is not supported on this processor. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_control.html">processor_control</a>, +<a href="processor_start.html">processor_start</a>, +<a href="processor_info.html">processor_info</a>, +<a href="host_processors.html">host_processors</a>. diff --git a/osfmk/man/processor_get_assignment.html b/osfmk/man/processor_get_assignment.html index d733ed364..933006750 100755 --- a/osfmk/man/processor_get_assignment.html +++ b/osfmk/man/processor_get_assignment.html @@ -1 +1,40 @@ -<h2>processor_get_assignment</h2> <hr> <p> <strong>Function</strong> - Get current assignment for a processor. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_get_assignment</strong> <strong>(processor_t</strong> <var>processor</var>, <strong>processor_set_name_t</strong> <var>assigned_set</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor</var> <dd> [in processor send right] The processor whose assignment is desired. <dt> <var>new_set</var> <dd> [out processor-set-name send right] The name port for the processor set to which <var>processor</var> is currently assigned. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_get_assignment</strong> function returns the name port for the processor set to which a desired processor is currently assigned. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_FAILURE</strong> <dd> Processor is either shut down of off-line. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_assign.html">processor_assign</a>, <a href="processor_set_create.html">processor_set_create</a>, <a href="processor_info.html">processor_info</a>, <a href="task_assign.html">task_assign</a>, <a href="thread_assign.html">thread_assign</a>. \ No newline at end of file +<h2>processor_get_assignment</h2> +<hr> +<p> +<strong>Function</strong> - Get current assignment for a processor. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_get_assignment</strong> + <strong>(processor_t</strong> <var>processor</var>, + <strong>processor_set_name_t</strong> <var>assigned_set</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor</var> +<dd> +[in processor send right] +The processor whose assignment is desired. +<dt> <var>new_set</var> +<dd> +[out processor-set-name send right] +The name port for the processor +set to which <var>processor</var> is currently assigned. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_get_assignment</strong> function returns the name port for the +processor set to which a desired processor is currently assigned. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>KERN_FAILURE</strong> +<dd> +Processor is either shut down of off-line. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_assign.html">processor_assign</a>, +<a href="processor_set_create.html">processor_set_create</a>, +<a href="processor_info.html">processor_info</a>, +<a href="task_assign.html">task_assign</a>, +<a href="thread_assign.html">thread_assign</a>. diff --git a/osfmk/man/processor_info.html b/osfmk/man/processor_info.html index ed7828020..b74e57491 100755 --- a/osfmk/man/processor_info.html +++ b/osfmk/man/processor_info.html @@ -1 +1,62 @@ -<h2>processor_info</h2> <hr> <p> <strong>Function</strong> - Return information about a processor. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_info</strong> <strong>(processor_t</strong> <var>processor</var>, <strong>processor_flavor_t</strong> <var>flavor</var>, <strong>host_t</strong> <var>host</var>, <strong>processor_info_t</strong> <var>processor_info</var>, <strong>mach_msg_type_number_t</strong> <var>processor_info_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor</var> <dd> [in processor send right] A processor port for which information is desired. <dt> <var>flavor</var> <dd> [in scalar] The type of information requested. <dl> <dt> <strong>PROCESSOR_BASIC_INFO</strong> <dd> Basic information, slot number, running status, etc. The returned structure is <strong>processor_basic_info</strong>. </dl> <dt> <var>host</var> <dd> [out host-name send right] The host on which the processor resides. This is the host name port. <dt> <var>processor_info</var> <dd> [out structure] Information about the processor. <dt> <var>processor_info_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_info</strong> function returns selected information for a processor, as specified by <var>flavor</var>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_start.html">processor_start</a>, <a href="processor_exit.html">processor_exit</a>, <a href="processor_control.html">processor_control</a>, <a href="host_processors.html">host_processors</a>. <p> Data Structures: <a href="processor_basic_info.html">processor_basic_info</a>. \ No newline at end of file +<h2>processor_info</h2> +<hr> +<p> +<strong>Function</strong> - Return information about a processor. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_info</strong> + <strong>(processor_t</strong> <var>processor</var>, + <strong>processor_flavor_t</strong> <var>flavor</var>, + <strong>host_t</strong> <var>host</var>, + <strong>processor_info_t</strong> <var>processor_info</var>, + <strong>mach_msg_type_number_t</strong> <var>processor_info_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor</var> +<dd> +[in processor send right] +A processor port for which information is +desired. +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of information requested. +<dl> +<dt> <strong>PROCESSOR_BASIC_INFO</strong> +<dd> +Basic information, slot number, running status, etc. The +returned structure is <strong>processor_basic_info</strong>. +</dl> +<dt> <var>host</var> +<dd> +[out host-name send right] +The host on which the processor resides. +This is the host name port. +<dt> <var>processor_info</var> +<dd> +[out structure] +Information about the processor. +<dt> <var>processor_info_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_info</strong> function returns selected information +for a processor, as specified by <var>flavor</var>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_start.html">processor_start</a>, +<a href="processor_exit.html">processor_exit</a>, +<a href="processor_control.html">processor_control</a>, +<a href="host_processors.html">host_processors</a>. +<p> +Data Structures: +<a href="processor_basic_info.html">processor_basic_info</a>. diff --git a/osfmk/man/processor_set_basic_info.html b/osfmk/man/processor_set_basic_info.html index a530b9f44..4c90ef930 100755 --- a/osfmk/man/processor_set_basic_info.html +++ b/osfmk/man/processor_set_basic_info.html @@ -1 +1,36 @@ -<h2>processor_set_basic_info</h2> <hr> <p> <strong>Structure</strong> - Defines the basic information about a processor set. <h3>SYNOPSIS</h3> <pre> <strong>struct processor_set_basic_info</strong> <strong>{</strong> <strong>int</strong> <var>processor_count</var><strong>;</strong> <strong>int</strong> <var>default_policy</var><strong>;</strong> <strong>};</strong> <strong>typedef struct processor_set_basic_info* processor_set_basic_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>processor_count</var> <dd> Number of processors in this set. <p> <dt> <var>default_policy</var> <dd> Default policy to assign to threads whose otherwise assigned policy is not enabled. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_basic_info</strong> structure defines the basic information available about a processor set. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_info.html"><strong>processor_set_info</strong></a>. <p> Data Structures: <a href="processor_set_load_info.html"></strong>processor_set_load_info<strong></a>. \ No newline at end of file +<h2>processor_set_basic_info</h2> +<hr> +<p> +<strong>Structure</strong> - Defines the basic information about a processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct processor_set_basic_info</strong> +<strong>{</strong> + <strong>int</strong> <var>processor_count</var><strong>;</strong> + <strong>int</strong> <var>default_policy</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct processor_set_basic_info* processor_set_basic_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>processor_count</var> +<dd> +Number of processors in this set. +<p> +<dt> <var>default_policy</var> +<dd> +Default policy to assign to threads whose otherwise assigned policy is +not enabled. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_basic_info</strong> structure defines the +basic information available about a processor set. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_info.html"><strong>processor_set_info</strong></a>. +<p> +Data Structures: +<a href="processor_set_load_info.html"></strong>processor_set_load_info<strong></a>. diff --git a/osfmk/man/processor_set_create.html b/osfmk/man/processor_set_create.html index 28942b00d..1b66d7424 100755 --- a/osfmk/man/processor_set_create.html +++ b/osfmk/man/processor_set_create.html @@ -1 +1,49 @@ -<h2>processor_set_create</h2> <hr> <p> <strong>Function</strong> - Create a new processor set object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_set_create</strong> <strong>(host_t</strong> <var>host_name</var>, <strong>processor_set_t</strong> <var>new_set</var>, <strong>processor_set_name_t</strong> <var>new_name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>host_name</var> <dd> [in host-name send right] The name (or control) port for the host on which the set is to be created. <dt> <var>new_set</var> <dd> [out processor-set-control send right] Control port used for performing operations on the new set. <dt> <var>new_name</var> <dd> [out processor-set-name send right] Name port used to identify the new set and obtain information about it. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_create</strong> function creates a new processor set and returns the two ports associated with it. The port returned in <var>new_set</var> is the control port representing the set. It is used to perform operations such as assigning processors, tasks or threads. The port returned in <var>new_name</var> is the name port which identifies the set, and is used to obtain information about the set. <h3>RETURN VALUES</h3> <p> Only generic values apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_destroy.html">processor_set_destroy</a>, <a href="processor_set_info.html">processor_set_info</a>, <a href="processor_assign.html">processor_assign</a>, <a href="task_assign.html">task_assign</a>, <a href="thread_assign.html">thread_assign</a>. \ No newline at end of file +<h2>processor_set_create</h2> +<hr> +<p> +<strong>Function</strong> - Create a new processor set object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_set_create</strong> + <strong>(host_t</strong> <var>host_name</var>, + <strong>processor_set_t</strong> <var>new_set</var>, + <strong>processor_set_name_t</strong> <var>new_name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>host_name</var> +<dd> +[in host-name send right] +The name (or control) port for the host on +which the set is to be created. +<dt> <var>new_set</var> +<dd> +[out processor-set-control send right] +Control port used for performing +operations on the new set. +<dt> <var>new_name</var> +<dd> +[out processor-set-name send right] +Name port used to identify the new +set and obtain information about it. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_create</strong> function creates a new processor +set and returns the +two ports associated with it. The port returned in <var>new_set</var> is the control port +representing the set. It is used to perform operations such +as assigning processors, +tasks or threads. The port returned in <var>new_name</var> is the name port which +identifies the set, and is used to obtain information about the set. +<h3>RETURN VALUES</h3> +<p> +Only generic values apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_destroy.html">processor_set_destroy</a>, +<a href="processor_set_info.html">processor_set_info</a>, +<a href="processor_assign.html">processor_assign</a>, +<a href="task_assign.html">task_assign</a>, +<a href="thread_assign.html">thread_assign</a>. diff --git a/osfmk/man/processor_set_default.html b/osfmk/man/processor_set_default.html index 6dee1b195..21a249a77 100755 --- a/osfmk/man/processor_set_default.html +++ b/osfmk/man/processor_set_default.html @@ -1 +1,39 @@ -<h2>processor_set_default</h2> <hr> <p> <strong>Function</strong> - Return the default processor set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_set_default</strong> <strong>(host_t</strong> <var>host</var>, <strong>processor_set_name_t</strong> <var>default_set_name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>host</var> <dd> [in host-name send right] The name (or control) port for the host for which the default processor set is desired. <dt> <var>default_set_name</var> <dd> [out processor-set-name send right] The returned name port for the default processor set. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_default</strong> function returns the name port for the default processor set for the specified host. The default processor set is used by all threads, tasks and processors that are not explicitly assigned to other sets. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_info.html">processor_set_info</a>, <a href="thread_assign.html">thread_assign</a>, <a href="task_assign.html">task_assign</a>. \ No newline at end of file +<h2>processor_set_default</h2> +<hr> +<p> +<strong>Function</strong> - Return the default processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_set_default</strong> + <strong>(host_t</strong> <var>host</var>, + <strong>processor_set_name_t</strong> <var>default_set_name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>host</var> +<dd> +[in host-name send right] +The name (or control) port for the host for +which the default processor set is desired. +<dt> <var>default_set_name</var> +<dd> +[out processor-set-name send right] +The returned name port for the +default processor set. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_default</strong> function returns the name +port for the default +processor set for the specified host. The default processor +set is used by all threads, +tasks and processors that are not explicitly assigned to other sets. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_info.html">processor_set_info</a>, +<a href="thread_assign.html">thread_assign</a>, +<a href="task_assign.html">task_assign</a>. diff --git a/osfmk/man/processor_set_destroy.html b/osfmk/man/processor_set_destroy.html index 4ee623e85..47f9a483a 100755 --- a/osfmk/man/processor_set_destroy.html +++ b/osfmk/man/processor_set_destroy.html @@ -1 +1,36 @@ -<h2>processor_set_destroy</h2> <hr> <p> <strong>Function</strong> - Destroy the target processor set object. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_set_destroy</strong> <strong>(processor_set_t</strong> <var>processor_set</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor_set</var> <dd> [in processor-set-control send right] The control port for the processor set to be destroyed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_destroy</strong> function destroys the specified processor set. Any assigned processors, tasks or threads are re-assigned to the default set. The object port (not the name port) for the processor set is required. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_DEFAULT_SET</strong> <dd> An attempt was made to destroy the default processor set. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_create.html">processor_set_create</a>, <a href="processor_assign.html">processor_assign</a>, <a href="task_assign.html">task_assign</a>, <a href="thread_assign.html">thread_assign</a>. \ No newline at end of file +<h2>processor_set_destroy</h2> +<hr> +<p> +<strong>Function</strong> - Destroy the target processor set object. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_set_destroy</strong> + <strong>(processor_set_t</strong> <var>processor_set</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor_set</var> +<dd> +[in processor-set-control send right] +The control port for the processor +set to be destroyed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_destroy</strong> function destroys the specified +processor set. Any +assigned processors, tasks or threads are re-assigned to the default set. The +object port (not the name port) for the processor set is required. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>KERN_DEFAULT_SET</strong> +<dd> +An attempt was made to destroy the default processor set. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_create.html">processor_set_create</a>, +<a href="processor_assign.html">processor_assign</a>, +<a href="task_assign.html">task_assign</a>, +<a href="thread_assign.html">thread_assign</a>. diff --git a/osfmk/man/processor_set_info.html b/osfmk/man/processor_set_info.html index b3d08803e..7d74a663a 100755 --- a/osfmk/man/processor_set_info.html +++ b/osfmk/man/processor_set_info.html @@ -1 +1,103 @@ -<h2>processor_set_info</h2> <hr> <p> <strong>Function</strong> - Return processor set state according to caller-specified flavor. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_set_info</strong> <strong>(processor_set_name_t</strong> <var>processor_set_name</var>, <strong>int</strong> <var>flavor</var>, <strong>host_t</strong> <var>host</var>, <strong>processor_set_info_t</strong> <var>processor_set_info</var>, <strong>mach_msg_type_number_t</strong> <var>processor_set_info_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor_set_name</var> <dd> [in processor-set-name send right] A processor set name (or control) port for which information is desired. <dt> <var>flavor</var> <dd> [in scalar] The type of information requested. <dl> <dt> <strong>PROCESSOR_SET_BASIC_INFO</strong> <dd> Basic information concerning the processor set (number of assigned processors and default policy). The returned structure is defined by <strong>processor_set_basic_info</strong>. <dt> <strong>PROCESSOR_SET_TIMESHARE_DEFAULT</strong> <dd> The base attributes for the timeshare scheduling policy. The returned structure is <strong>policy_timeshare_base</strong>. <dt> <strong>PROCESSOR_SET_FIFO_DEFAULT</strong> <dd> The base attributes for the FIFO scheduling policy. The returned structure is <strong>policy_fifo_base</strong>. <dt> <strong>PROCESSOR_SET_RR_DEFAULT</strong> <dd> The base attributes for the round-robin scheduling policy. The returned structure is <strong>policy_rr_base</strong>. <dt> <strong>PROCESSOR_SET_TIMESHARE_LIMITS</strong> <dd> Limits on the allowed timeshare policy attributes. The returned structure is defined by <strong>policy_timeshare_limit</strong>. <dt> <strong>PROCESSOR_SET_RR_LIMITS</strong> <dd> Limits on the allowed round robin policy attributes. The returned structure is defined by <strong>policy_rr_limit</strong>. <dt> <strong>PROCESSOR_SET_FIFO_LIMITS</strong> <dd> Limits on the allowed first-in, first-out policy attributes. The returned structure is defined by <strong>policy_fifo_limit</strong>. <dt> <strong>PROCESSOR_SET_ENABLED_POLICIES</strong> <dd> The set of enabled policies. The returned data is a bit-vector. </dl> <dt> <var>host</var> <dd> [out host-name send right] The name port for the host on which the processor set resides. <dt> <var>processor_set_info</var> <dd> [out structure] Information about the processor set. <dt> <var>processor_set_info_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_info</strong> function returns selected information for a processor set, as specified by <var>flavor</var>. <h3>NOTES</h3> <p> A processor set has a single default scheduling policy in effect for it (as returned by <strong>PROCESSOR_SET_BASIC_INFO</strong>), so only one of the default scheduling structures has valid information. On the other hand, a processor set maintains limits for all defined scheduling policies, so all of the scheduling limit structures return valid values. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_statistics.html">processor_set_statistics</a>, <a href="processor_set_create.html">processor_set_create</a>, <a href="processor_set_default.html">processor_set_default</a>, <a href="processor_assign.html">processor_assign</a>, <a href="P_set_policy_control.html">processor_set_policy_control</a>. <p> Data Structures: <a href="processor_set_basic_info.html">processor_set_basic_info</a>, <a href="policy_timeshare_info.html">policy_timeshare_info</a>, <a href="policy_rr_info.html">policy_rr_info</a>, <a href="policy_fifo_info.html">policy_fifo_info</a>. \ No newline at end of file +<h2>processor_set_info</h2> +<hr> +<p> +<strong>Function</strong> - Return processor set state according to caller-specified flavor. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_set_info</strong> + <strong>(processor_set_name_t</strong> <var>processor_set_name</var>, + <strong>int</strong> <var>flavor</var>, + <strong>host_t</strong> <var>host</var>, + <strong>processor_set_info_t</strong> <var>processor_set_info</var>, + <strong>mach_msg_type_number_t</strong> <var>processor_set_info_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor_set_name</var> +<dd> +[in processor-set-name send right] +A processor set name (or control) +port for which information is desired. +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of information requested. +<dl> +<dt> <strong>PROCESSOR_SET_BASIC_INFO</strong> +<dd> +Basic information concerning the processor set (number of +assigned processors and default policy). The returned structure +is defined by <strong>processor_set_basic_info</strong>. +<dt> <strong>PROCESSOR_SET_TIMESHARE_DEFAULT</strong> +<dd> +The base attributes for the timeshare scheduling policy. The +returned structure is <strong>policy_timeshare_base</strong>. +<dt> <strong>PROCESSOR_SET_FIFO_DEFAULT</strong> +<dd> +The base attributes for the FIFO scheduling policy. The +returned structure is <strong>policy_fifo_base</strong>. +<dt> <strong>PROCESSOR_SET_RR_DEFAULT</strong> +<dd> +The base attributes for the round-robin scheduling policy. The +returned structure is <strong>policy_rr_base</strong>. +<dt> <strong>PROCESSOR_SET_TIMESHARE_LIMITS</strong> +<dd> +Limits on the allowed timeshare policy attributes. The +returned structure is defined by <strong>policy_timeshare_limit</strong>. +<dt> <strong>PROCESSOR_SET_RR_LIMITS</strong> +<dd> +Limits on the allowed round robin policy attributes. The +returned structure is defined by <strong>policy_rr_limit</strong>. +<dt> <strong>PROCESSOR_SET_FIFO_LIMITS</strong> +<dd> +Limits on the allowed first-in, first-out policy attributes. The +returned structure is defined by <strong>policy_fifo_limit</strong>. +<dt> <strong>PROCESSOR_SET_ENABLED_POLICIES</strong> +<dd> +The set of enabled policies. The returned data is a bit-vector. +</dl> +<dt> <var>host</var> +<dd> +[out host-name send right] +The name port for the host on which the +processor set resides. +<dt> <var>processor_set_info</var> +<dd> +[out structure] +Information about the processor set. +<dt> <var>processor_set_info_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_info</strong> function returns selected information +for a processor set, as specified by <var>flavor</var>. +<h3>NOTES</h3> +<p> +A processor set has a single default scheduling policy in effect for it (as +returned by <strong>PROCESSOR_SET_BASIC_INFO</strong>), so only one of the default +scheduling structures has valid information. On the other hand, +a processor set +maintains limits for all defined scheduling policies, so all +of the scheduling limit +structures return valid values. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_statistics.html">processor_set_statistics</a>, +<a href="processor_set_create.html">processor_set_create</a>, +<a href="processor_set_default.html">processor_set_default</a>, +<a href="processor_assign.html">processor_assign</a>, +<a href="P_set_policy_control.html">processor_set_policy_control</a>. +<p> +Data Structures: +<a href="processor_set_basic_info.html">processor_set_basic_info</a>, +<a href="policy_timeshare_info.html">policy_timeshare_info</a>, +<a href="policy_rr_info.html">policy_rr_info</a>, +<a href="policy_fifo_info.html">policy_fifo_info</a>. diff --git a/osfmk/man/processor_set_load_info.html b/osfmk/man/processor_set_load_info.html index feda7f32e..f93fede2a 100755 --- a/osfmk/man/processor_set_load_info.html +++ b/osfmk/man/processor_set_load_info.html @@ -1 +1,45 @@ -<h2>processor_set_load_info</h2> <hr> <p> <strong>Structure</strong> - Defines the scheduling statistics for a processor set. <h3>SYNOPSIS</h3> <pre> <strong>struct processor_set_load_info</strong> <strong>{</strong> <strong>int</strong> <var>task_count</var><strong>;</strong> <strong>int</strong> <var>thread_count</var><strong>;</strong> <strong>integer_t</strong> <var>load_average</var><strong>;</strong> <strong>integer_t</strong> <var>mach_factor</var><strong>;</strong> <strong>};</strong> <strong>typedef struct processor_set_load_info* processor_set_load_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>task_count</var> <dd> Number of tasks currently assigned to this processor set <p> <dt> <var>thread_count</var> <dd> Number of threads currently assigned to this processor set <p> <dt> <var>load_average</var> <dd> Average number of runnable processes divided by number of CPUs <p> <dt> <var>mach_factor</var> <dd> The processing resources available to a new thread\(emthe number of CPUs divided by (1 + the number of threads) </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_load_info</strong> structure defines the scheduling statistics maintained for a processor set. <h3>RELATED INFORMATION</h3> <p> <p> Data Structures: <a href="processor_set_basic_info.html"><strong>processor_set_basic_info</strong></a>. \ No newline at end of file +<h2>processor_set_load_info</h2> +<hr> +<p> +<strong>Structure</strong> - Defines the scheduling statistics for a processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct processor_set_load_info</strong> +<strong>{</strong> + <strong>int</strong> <var>task_count</var><strong>;</strong> + <strong>int</strong> <var>thread_count</var><strong>;</strong> + <strong>integer_t</strong> <var>load_average</var><strong>;</strong> + <strong>integer_t</strong> <var>mach_factor</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct processor_set_load_info* processor_set_load_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>task_count</var> +<dd> +Number of tasks currently assigned to this processor set +<p> +<dt> <var>thread_count</var> +<dd> +Number of threads currently assigned to this processor set +<p> +<dt> <var>load_average</var> +<dd> +Average number of runnable processes divided by number of CPUs +<p> +<dt> <var>mach_factor</var> +<dd> +The processing resources available to a new thread\(emthe number of +CPUs divided by (1 + the number of threads) +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_load_info</strong> structure defines the scheduling +statistics +maintained for a processor set. +<h3>RELATED INFORMATION</h3> +<p> +<p> +Data Structures: +<a href="processor_set_basic_info.html"><strong>processor_set_basic_info</strong></a>. diff --git a/osfmk/man/processor_set_max_priority.html b/osfmk/man/processor_set_max_priority.html index 804cbc21c..957e0ef80 100755 --- a/osfmk/man/processor_set_max_priority.html +++ b/osfmk/man/processor_set_max_priority.html @@ -1 +1,47 @@ -<h2>processor_set_max_priority</h2> <hr> <p> <strong>Function</strong> - Sets the maximum scheduling priority for a processor set. <h3>SYNOPSIS</h3> <pre> <strong>#include< mach/mach_host.h></strong> <strong>kern_return_t processor_set_max_priority</strong> <strong>(processor_set_t</strong> <var>processor_set</var>, <strong>int</strong> <var>priority</var>, <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor_set</var> <dd> [in processor-set-control port] The control port for the processor set whose maximum scheduling priority is to be set. <dt> <var>priority</var> <dd> [in scalar] The new priority for the processor set. <dt> <var>change_threads</var> <dd> [in scalar] True if the maximum priority of existing threads assigned to this processor set should also be changed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_max_priority</strong> function sets the maximum scheduling <var>priority</var> for <var>processor_set</var>. The maximum <var>priority</var> of a processor set is used only when creating new threads. A new thread's maximum <var>priority</var> is set to that of its assigned processor set. When assigned to a processor set, a thread's maximum <var>priority</var> is reduced, if necessary, to that of its new processor set; its current <var>priority</var> is also reduced, as needed. Changing the maximum <var>priority</var> of a processor set does not affect the <var>priority</var> of the currently assigned threads unless <var>change_threads</var> is TRUE. If this <var>priority</var> change violates the maximum <var>priority</var> of some threads, their maximum priorities will be reduced to match. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_assign.html">thread_assign</a>. \ No newline at end of file +<h2>processor_set_max_priority</h2> +<hr> +<p> +<strong>Function</strong> - Sets the maximum scheduling priority for a processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include< mach/mach_host.h></strong> + +<strong>kern_return_t processor_set_max_priority</strong> + <strong>(processor_set_t</strong> <var>processor_set</var>, + <strong>int</strong> <var>priority</var>, + <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor_set</var> +<dd> +[in processor-set-control port] The control port for the processor set whose maximum scheduling priority is to be set. +<dt> <var>priority</var> +<dd> +[in scalar] The new priority for the processor set. +<dt> <var>change_threads</var> +<dd> +[in scalar] True if the maximum priority of existing threads assigned to this processor set should also be changed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_max_priority</strong> +function sets the maximum scheduling <var>priority</var> for +<var>processor_set</var>. The maximum <var>priority</var> of a +processor set is used only when creating new threads. A new thread's +maximum <var>priority</var> is set to that of its assigned processor +set. When assigned to a processor set, a thread's maximum +<var>priority</var> is reduced, if necessary, to that of its new +processor set; its current <var>priority</var> is also reduced, as +needed. Changing the maximum <var>priority</var> of a processor set +does not affect the <var>priority</var> of the currently assigned +threads unless <var>change_threads</var> is TRUE. If this +<var>priority</var> change violates the maximum <var>priority</var> of +some threads, their maximum priorities will be reduced to match. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_assign.html">thread_assign</a>. diff --git a/osfmk/man/processor_set_statistics.html b/osfmk/man/processor_set_statistics.html index 5bd65369d..315304bfc 100755 --- a/osfmk/man/processor_set_statistics.html +++ b/osfmk/man/processor_set_statistics.html @@ -1 +1,53 @@ -<h2>processor_set_statistics</h2> <hr> <p> <strong>Function</strong> - Return scheduling statistics for a processor set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_set_statistics</strong> <strong>(processor_set_t</strong> <var>processor_set_control</var>, <strong>processor_set_flavor_t</strong> <var>flavor</var>, <strong>processor_set_info_t</strong> <var>processor_set_info</var>, <strong>mach_msg_type_number_t</strong> <var>processor_set_info_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor_set_control</var> <dd> [in processor-set-control send right] A processor set control port for which information is desired. <dt> <var>flavor</var> <dd> [in scalar] The type of information requested. <dl> <dt> <strong>PROCESSOR_SET_LOAD_INFO</strong> <dd> Load statistics for the processor set. The returned structure is <strong>processor_set_load_info</strong>. </dl> <dt> <var>processor_set_info</var> <dd> [out structure] Information about the processor set. <dt> <var>processor_set_info_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_statistics</strong> function returns statistics for a processor set as specified by <var>flavor</var>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_info.html">processor_set_info</a>. <p> Data Structures: <a href="processor_set_load_info.html">processor_set_load_info</a>. \ No newline at end of file +<h2>processor_set_statistics</h2> +<hr> +<p> +<strong>Function</strong> - Return scheduling statistics for a processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_set_statistics</strong> + <strong>(processor_set_t</strong> <var>processor_set_control</var>, + <strong>processor_set_flavor_t</strong> <var>flavor</var>, + <strong>processor_set_info_t</strong> <var>processor_set_info</var>, + <strong>mach_msg_type_number_t</strong> <var>processor_set_info_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor_set_control</var> +<dd> +[in processor-set-control send right] +A processor set control port for +which information is desired. +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of information requested. +<dl> +<dt> <strong>PROCESSOR_SET_LOAD_INFO</strong> +<dd> +Load statistics for the processor set. The returned structure is +<strong>processor_set_load_info</strong>. +</dl> +<dt> <var>processor_set_info</var> +<dd> +[out structure] +Information about the processor set. +<dt> <var>processor_set_info_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_statistics</strong> function returns statistics +for a processor set as specified by <var>flavor</var>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_info.html">processor_set_info</a>. +<p> +Data Structures: +<a href="processor_set_load_info.html">processor_set_load_info</a>. diff --git a/osfmk/man/processor_set_tasks.html b/osfmk/man/processor_set_tasks.html index 7f2827eed..01c3eaec9 100755 --- a/osfmk/man/processor_set_tasks.html +++ b/osfmk/man/processor_set_tasks.html @@ -1 +1,41 @@ -<h2>processor_set_tasks</h2> <hr> <p> <strong>Function</strong> - Return a list of pointers to all tasks currently assigned to the target processor set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_set_tasks</strong> <strong>(processor_set_t</strong> <var>processor_set</var>, <strong>task_port_array_t</strong> <var>task_list</var>, <strong>mach_msg_type_number_t*</strong> <var>task_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor_set</var> <dd> [in processor-set-control send right] A processor set control port for which information is desired. <dt> <var>task_list</var> <dd> [out pointer to dynamic array of task send rights] The returned set of ports naming the tasks currently assigned to <var>processor_set</var>. <dt> <var>task_count</var> <dd> [out scalar] The number of tasks returned in <var>task_list</var>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_tasks</strong> function returns send rights to the kernel ports for each task currently assigned to <var>processor_set</var>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_threads.html">processor_set_threads</a>, <a href="task_assign.html">task_assign</a>, <a href="thread_assign.html">thread_assign</a>. \ No newline at end of file +<h2>processor_set_tasks</h2> +<hr> +<p> +<strong>Function</strong> - Return a list of pointers to all tasks currently assigned to the target processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_set_tasks</strong> + <strong>(processor_set_t</strong> <var>processor_set</var>, + <strong>task_port_array_t</strong> <var>task_list</var>, + <strong>mach_msg_type_number_t*</strong> <var>task_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor_set</var> +<dd> +[in processor-set-control send right] +A processor set control port for +which information is desired. +<dt> <var>task_list</var> +<dd> +[out pointer to dynamic array of task send rights] +The returned set of +ports naming the tasks currently assigned to <var>processor_set</var>. +<dt> <var>task_count</var> +<dd> +[out scalar] +The number of tasks returned in <var>task_list</var>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_tasks</strong> function returns send rights +to the kernel ports for each task currently assigned to <var>processor_set</var>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_threads.html">processor_set_threads</a>, +<a href="task_assign.html">task_assign</a>, +<a href="thread_assign.html">thread_assign</a>. diff --git a/osfmk/man/processor_set_threads.html b/osfmk/man/processor_set_threads.html index 7bdfb6626..0af5f9c51 100755 --- a/osfmk/man/processor_set_threads.html +++ b/osfmk/man/processor_set_threads.html @@ -1 +1,41 @@ -<h2>processor_set_threads</h2> <hr> <p> <strong>Function</strong> - Return a list of pointers to all threads currently assigned to the target processor set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t processor_set_threads</strong> <strong>(processor_set_t</strong> <var>processor_set</var>, <strong>thread_port_array_t</strong> <var>thread_list</var>, <strong>mach_msg_type_number_t*</strong> <var>thread_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor_set</var> <dd> [in processor-set-control send right] A processor set control port for which information is desired. <dt> <var>thread_list</var> <dd> [out pointer to dynamic array of thread send rights] The returned set of ports naming the threads currently assigned to <var>processor_set</var>. <dt> <var>thread_count</var> <dd> [out scalar] The number of threads returned in <var>thread_list</var>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_set_threads</strong> function returns send rights to the kernel ports for each thread currently assigned to <var>processor_set</var>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_set_tasks.html">processor_set_tasks</a>, <a href="task_assign.html">task_assign</a>, <a href="thread_assign.html">thread_assign</a>. \ No newline at end of file +<h2>processor_set_threads</h2> +<hr> +<p> +<strong>Function</strong> - Return a list of pointers to all threads currently assigned to the target processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t processor_set_threads</strong> + <strong>(processor_set_t</strong> <var>processor_set</var>, + <strong>thread_port_array_t</strong> <var>thread_list</var>, + <strong>mach_msg_type_number_t*</strong> <var>thread_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor_set</var> +<dd> +[in processor-set-control send right] +A processor set control port for +which information is desired. +<dt> <var>thread_list</var> +<dd> +[out pointer to dynamic array of thread send rights] +The returned set of +ports naming the threads currently assigned to <var>processor_set</var>. +<dt> <var>thread_count</var> +<dd> +[out scalar] +The number of threads returned in <var>thread_list</var>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_set_threads</strong> function returns send rights +to the kernel ports for each thread currently assigned to <var>processor_set</var>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_set_tasks.html">processor_set_tasks</a>, +<a href="task_assign.html">task_assign</a>, +<a href="thread_assign.html">thread_assign</a>. diff --git a/osfmk/man/processor_start.html b/osfmk/man/processor_start.html index 0c9f4b087..afe1494c8 100755 --- a/osfmk/man/processor_start.html +++ b/osfmk/man/processor_start.html @@ -1 +1,46 @@ -<h2>processor_start</h2> <hr> <p> <strong>Function</strong> - Start a processor. <h3>SYNOPSIS</h3> <pre> <strong>#include<mach/mach_host.h></strong> <strong>kern_return_t processor_start</strong> <strong>(processor_t</strong> <var>processor</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>processor</var> <dd> [in processor send right] The processor to be controlled. </dl> <h3>DESCRIPTION</h3> <p> The <strong>processor_start</strong> function allows privileged software to start a processor in a multi-processor that so allows it. A newly started processor is assigned to the default processor set. The interpretation of this operation is machine dependent. <h3>NOTES</h3> <p> This operation is machine dependent. It may do nothing. <h3>CAUTIONS</h3> <p> The ability to restart an exited processor is machine dependent. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_FAILURE</strong> <dd> The operation was not performed. A likely reason is that it is not supported on this processor. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="processor_control.html">processor_control</a>, <a href="processor_exit.html">processor_exit</a>, <a href="processor_info.html">processor_info</a>, <a href="host_processors.html">host_processors</a>. \ No newline at end of file +<h2>processor_start</h2> +<hr> +<p> +<strong>Function</strong> - Start a processor. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<mach/mach_host.h></strong> + +<strong>kern_return_t processor_start</strong> + <strong>(processor_t</strong> <var>processor</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>processor</var> +<dd> +[in processor send right] +The processor to be controlled. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>processor_start</strong> function allows privileged software +to start a processor in +a multi-processor that so allows it. A newly started processor +is assigned to the +default processor set. The interpretation of this operation +is machine dependent. +<h3>NOTES</h3> +<p> +This operation is machine dependent. It may do nothing. +<h3>CAUTIONS</h3> +<p> +The ability to restart an exited processor is machine dependent. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>KERN_FAILURE</strong> +<dd> +The operation was not performed. A likely reason is that it +is not supported on this processor. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="processor_control.html">processor_control</a>, +<a href="processor_exit.html">processor_exit</a>, +<a href="processor_info.html">processor_info</a>, +<a href="host_processors.html">host_processors</a>. diff --git a/osfmk/man/prof_server.html b/osfmk/man/prof_server.html index 44d09f1e9..009d68cb6 100755 --- a/osfmk/man/prof_server.html +++ b/osfmk/man/prof_server.html @@ -1 +1,49 @@ -<h2>prof_server</h2> <hr> <p> <strong>Function</strong> - Handle the next kernel-generated PC sample message. <h3>SYNOPSIS</h3> <pre> <strong>boolean_t prof_server</strong> <strong>(mach_msg_header_t</strong> <var>request_msg</var>, <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>in_msg</var> <dd> [pointer to in structure] The sample message received from the kernel. <p> <dt> <var>out_msg</var> <dd> [out structure] Not used. </dl> <h3>DESCRIPTION</h3> <p> The <strong>prof_server</strong> function is the MIG generated server handling function to handle messages from the kernel corresponding to program counter (profiling) samples. Such messages are delivered to the task or thread sample port set by <strong>task_sample</strong> or <strong>thread_sample</strong>. The <strong>prof_server</strong> function performs all necessary argument handling for this kernel message and calls the appropriate handling function. These functions must be supplied by the caller. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>TRUE</strong> <dd> The message was handled and the appropriate function was called. <p> <dt> <strong>FALSE</strong> <dd> The message did not apply to the sample mechanism and no other action was taken. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="receive_samples.html"><strong>receive_samples<strong></a>. \ No newline at end of file +<h2>prof_server</h2> +<hr> +<p> +<strong>Function</strong> - Handle the next kernel-generated PC sample message. +<h3>SYNOPSIS</h3> +<pre> +<strong>boolean_t prof_server</strong> + <strong>(mach_msg_header_t</strong> <var>request_msg</var>, + <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>in_msg</var> +<dd> +[pointer to in structure] +The sample message received from the kernel. +<p> +<dt> <var>out_msg</var> +<dd> +[out structure] +Not used. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>prof_server</strong> function is the MIG generated server +handling function to +handle messages from the kernel corresponding to program counter (profiling) +samples. Such messages are delivered to the task or thread sample port set by +<strong>task_sample</strong> or <strong>thread_sample</strong>. The <strong>prof_server</strong> +function performs all +necessary argument handling for this kernel message and calls the appropriate +handling function. These functions must be supplied by the caller. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The message was handled and the appropriate function was called. +<p> +<dt> <strong>FALSE</strong> +<dd> +The message did not apply to the sample mechanism and no other +action was taken. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="receive_samples.html"><strong>receive_samples<strong></a>. diff --git a/osfmk/man/receive_samples.html b/osfmk/man/receive_samples.html index 9268ac683..fb61dfd9f 100755 --- a/osfmk/man/receive_samples.html +++ b/osfmk/man/receive_samples.html @@ -1 +1,51 @@ -<h2>receive_samples</h2> <p> Server Interface - Handles the occurrence of a PC sampling message <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t receive_samples</strong> <strong>(mach_port_t</strong> <var>sample_port</var>, <strong>sample_array_t</strong> <var>samples</var>, <strong>mach_msg_type_number_t</strong> <var>sample_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>sample_port</var> <dd> [in sample (receive) right] The port to which the sample message was sent. <dt> <var>samples</var> <dd> [pointer to in array of vm_address_t] An array of PC sample values. <dt> <var>sample_count</var> <dd> [in scalar] The number of values in samples. </dl> <h3>DESCRIPTION</h3> <p> A <strong>receive_samples</strong> function is called by <strong>prof_server</strong> as the result of a kernel message indicating that a set of program counter samples has been gathered. The parameter <var>sample_port</var> specifies the port named via a previous call to <strong>task_sample</strong> or <strong>thread_sample</strong>. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual addresses in the <var>samples</var> parameter. <h3>RETURN VALUE</h3> <p> Irrelevant. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_sample.html"><strong>task_sample</strong></a>, <a href="thread_sample.html"><strong>thread_sample</strong></a>, <a href="prof_server.html"><strong>prof_server</strong></a>. \ No newline at end of file +<h2>receive_samples</h2> +<p> +Server Interface - Handles the occurrence of a PC sampling message + +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t receive_samples</strong> + <strong>(mach_port_t</strong> <var>sample_port</var>, + <strong>sample_array_t</strong> <var>samples</var>, + <strong>mach_msg_type_number_t</strong> <var>sample_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>sample_port</var> +<dd> +[in sample (receive) right] The port to which the sample message was +sent. + +<dt> <var>samples</var> +<dd> +[pointer to in array of vm_address_t] An array of PC sample values. + +<dt> <var>sample_count</var> +<dd> +[in scalar] The number of values in samples. +</dl> + +<h3>DESCRIPTION</h3> +<p> +A <strong>receive_samples</strong> function is called by +<strong>prof_server</strong> as the result of a kernel +message indicating that a set of program counter samples has been gathered. +The parameter <var>sample_port</var> specifies the port named via +a previous call to <strong>task_sample</strong> +or <strong>thread_sample</strong>. + +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual addresses +in the <var>samples</var> parameter. + +<h3>RETURN VALUE</h3> +<p> +Irrelevant. + +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_sample.html"><strong>task_sample</strong></a>, +<a href="thread_sample.html"><strong>thread_sample</strong></a>, +<a href="prof_server.html"><strong>prof_server</strong></a>. diff --git a/osfmk/man/semaphore_create.html b/osfmk/man/semaphore_create.html index 2d552c2bd..fcccd8f9e 100755 --- a/osfmk/man/semaphore_create.html +++ b/osfmk/man/semaphore_create.html @@ -1 +1,78 @@ -<h2>semaphore_create</h2> <hr> <p> <strong>Function</strong> - Create a new semaphore. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t semaphore_create</strong> <strong>(task_t</strong> <var>task</var>, <strong>semaphore_t</strong> <var>*semaphore</var>, <strong>int</strong> <var>policy</var>, <strong>int</strong> <var>value</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>task</var> <dd> [in task port] The task receiving the send right of the newly created semaphore. <p> <dt> <var>semaphore</var> <dd> [out send right] The port naming the created semaphore. <p> <dt> <var>policy</var> <dd> [in scalar] The blocked thread wakeup policy for the newly created semaphore. Valid policies are: <dl> <p> <dt> SYNC_POLICY_FIFO <dd> a first-in-first-out policy for scheduling thread wakeup. <p> <dt> SYNC_POLICY_FIXED_PRIORITY <dd> a fixed priority policy for scheduling thread wakeup. </dl> <p> <dt> <var>value</var> <dd> [in scalar] The initial value of the semaphore count. </dl> <h3>DESCRIPTION</h3> <p> The <strong>semaphore_create</strong> function creates a new semaphore, associates the created semaphore with the specified task, and returns a send right naming the new semaphore. In order to support a robust producer/consumer communication service, Interrupt Service Routines (ISR) must be able to signal semaphores. The semaphore synchronizer service is designed to allow user-level device drivers to perform signal operations, eliminating the need for event counters. Device drivers which utilize semaphores are responsible for creating (via <strong>semaphore_create</strong>) and exporting (via <strong>device_get_status</strong>) semaphores for user level access. Device driver semaphore creation is done at device initialization time. Device drivers may support multiple semaphores. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The task argument or the policy argument was invalid, or the initial value of the semaphore was invalid. <p> <dt> <strong>KERN_RESOURCE_SHORTAGE</strong> <dd> The kernel could not allocate the semaphore. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The semaphore was successfully created. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>, <a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>, <a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>, <a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>, <a href="device_get_status.html"><strong>device_get_status</strong></a>. \ No newline at end of file +<h2>semaphore_create</h2> +<hr> +<p> +<strong>Function</strong> - Create a new semaphore. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t semaphore_create</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>semaphore_t</strong> <var>*semaphore</var>, + <strong>int</strong> <var>policy</var>, + <strong>int</strong> <var>value</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>task</var> +<dd> +[in task port] The task receiving the send right of the newly created semaphore. +<p> +<dt> <var>semaphore</var> +<dd> +[out send right] The port naming the created semaphore. +<p> +<dt> <var>policy</var> +<dd> +[in scalar] The blocked thread wakeup policy for the newly created semaphore. Valid policies are: +<dl> +<p> + <dt> SYNC_POLICY_FIFO +<dd> +a first-in-first-out policy for scheduling thread wakeup. + <p> + <dt> SYNC_POLICY_FIXED_PRIORITY +<dd> +a fixed priority policy for scheduling thread wakeup. + </dl> + <p> +<dt> <var>value</var> +<dd> +[in scalar] The initial value of the semaphore count. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>semaphore_create</strong> function creates a new semaphore, associates the +created semaphore with the specified task, and returns a send right +naming the new semaphore. In order to support a robust +producer/consumer communication service, Interrupt Service Routines +(ISR) must be able to signal semaphores. The semaphore synchronizer +service is designed to allow user-level device drivers to perform +signal operations, eliminating the need for event counters. Device +drivers which utilize semaphores are responsible for creating (via +<strong>semaphore_create</strong>) and exporting (via <strong>device_get_status</strong>) +semaphores for +user level access. Device driver semaphore creation is done at device +initialization time. Device drivers may support multiple semaphores. +<h3>RETURN VALUES</h3> +<dl> + <p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The task argument or the policy argument was invalid, + or the initial value of the semaphore was invalid. + <p> +<dt> <strong>KERN_RESOURCE_SHORTAGE</strong> +<dd> +The kernel could not allocate the semaphore. + <p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The semaphore was successfully created. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>, +<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>, +<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>, +<a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>, +<a href="device_get_status.html"><strong>device_get_status</strong></a>. diff --git a/osfmk/man/semaphore_destroy.html b/osfmk/man/semaphore_destroy.html index 42202ec53..9a2505d95 100755 --- a/osfmk/man/semaphore_destroy.html +++ b/osfmk/man/semaphore_destroy.html @@ -1 +1,58 @@ -<h2>semaphore_destroy</h2> <hr> <p> <strong>Function</strong> - Destroy a semaphore. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t semaphore_destroy</strong> <strong>(task_t</strong> <var>task</var>, <strong>semaphore_t</strong> <var>semaphore</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task port] The task associated with the target semaphore. <p> <dt> <var>semaphore</var> <dd> [in send right] The port naming the semaphore to be destroyed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>semaphore_destroy</strong> function destroys a semaphore. All send rights naming the semaphore become dead names. Threads waiting on the semaphore become unblocked with the return from the <strong>semaphore_wait</strong> call indicating that the semaphore was destroyed. A call to <strong>semaphore_destroy</strong> succeeds only if the semaphore is associated with the specified task. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> Either, or both, the task or semaphore arguments were invalid. <p> <dt> <strong>KERN_INVALID_RIGHT</strong> <dd> The specified task does not own the specified semaphore. <p> <dt> <strong>KERN_TERMINATED</strong> <dd> The specified semaphore was previously destroyed. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The semaphore was destroyed. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="semaphore_create.html"><strong>semaphore_create</strong></a>, <a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>, <a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>, <a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>, <a href="device_get_status.html"><strong>device_get_status</strong></a>. \ No newline at end of file +<h2>semaphore_destroy</h2> +<hr> +<p> +<strong>Function</strong> - Destroy a semaphore. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t semaphore_destroy</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>semaphore_t</strong> <var>semaphore</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task port] The task associated with the target semaphore. +<p> +<dt> <var>semaphore</var> +<dd> +[in send right] The port naming the semaphore to be destroyed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>semaphore_destroy</strong> function destroys a semaphore. +All send rights +naming the semaphore become dead names. Threads waiting on the +semaphore become unblocked with the return from the +<strong>semaphore_wait</strong> +call indicating that the semaphore was destroyed. A call to +<strong>semaphore_destroy</strong> succeeds only if the semaphore is associated +with the specified task. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +Either, or both, the task or semaphore arguments were invalid. +<p> +<dt> <strong>KERN_INVALID_RIGHT</strong> +<dd> +The specified task does not own the specified semaphore. +<p> +<dt> <strong>KERN_TERMINATED</strong> +<dd> +The specified semaphore was previously destroyed. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The semaphore was destroyed. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="semaphore_create.html"><strong>semaphore_create</strong></a>, +<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>, +<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>, +<a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>, +<a href="device_get_status.html"><strong>device_get_status</strong></a>. diff --git a/osfmk/man/semaphore_signal.html b/osfmk/man/semaphore_signal.html index c3691eb67..fcb794fc0 100755 --- a/osfmk/man/semaphore_signal.html +++ b/osfmk/man/semaphore_signal.html @@ -1 +1,49 @@ -<h2>semaphore_signal</h2> <hr> <p> <strong>Function</strong> - Increments the semaphore count. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t semaphore_signal</strong> <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>semaphore</var> <dd> [in send right] The port naming the semaphore to be signalled. </dl> <h3>DESCRIPTION</h3> <p> The <strong>semaphore_signal</strong> function increments the semaphore count. If the count goes non-negative (i.e. greater than or equal to 0) and a thread is blocked on the semaphore, then the waiting thread is scheduled to execute. If multiple threads are blocked on the semaphore, the thread scheduled to execute is selected according to the wakeup policy of the semaphore (set when the semaphore was created via <strong>semaphore_create</strong>). Device driver interrupt service routines may safely execute <strong>semaphore_signal</strong> operations without causing a deadlock. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified semaphore is invalid. <p> <dt> <strong>KERN_TERMINATED</strong> <dd> The specified semaphore has been destroyed. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The semaphore has been signalled. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="semaphore_create.html"><strong>semaphore_create</strong></a>, <a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>, <a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>, <a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>, <a href="device_get_status.html"><strong>device_get_status</strong></a>. \ No newline at end of file +<h2>semaphore_signal</h2> +<hr> +<p> +<strong>Function</strong> - Increments the semaphore count. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t semaphore_signal</strong> + <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>semaphore</var> +<dd> +[in send right] The port naming the semaphore to be signalled. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>semaphore_signal</strong> function increments the semaphore count. If the +count goes non-negative (i.e. greater than or equal to 0) and a thread +is blocked on the semaphore, then the waiting thread is scheduled to +execute. If multiple threads are blocked on the semaphore, the thread +scheduled to execute is selected according to the wakeup policy of the +semaphore (set when the semaphore was created via <strong>semaphore_create</strong>). +Device driver interrupt service routines may safely execute +<strong>semaphore_signal</strong> operations without causing a deadlock. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The specified semaphore is invalid. +<p> +<dt> <strong>KERN_TERMINATED</strong> +<dd> +The specified semaphore has been destroyed. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The semaphore has been signalled. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="semaphore_create.html"><strong>semaphore_create</strong></a>, +<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>, +<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>, +<a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>, +<a href="device_get_status.html"><strong>device_get_status</strong></a>. diff --git a/osfmk/man/semaphore_signal_all.html b/osfmk/man/semaphore_signal_all.html index 1bbf86bb3..8b936c948 100755 --- a/osfmk/man/semaphore_signal_all.html +++ b/osfmk/man/semaphore_signal_all.html @@ -1 +1,42 @@ -<h2>semaphore_signal_all</h2> <hr> <p> <strong>Function</strong> - Wake up all threads blocked on a semaphore. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t semaphore_signal_all</strong> <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>semaphore</var> <dd> [in send right] The port naming the semaphore to be signalled. </dl> <h3>DESCRIPTION</h3> <p> The <strong>semaphore_signal_all</strong> function wakes up all of the threads blocked on the semaphore. The semaphore count is reset to zero. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified semaphore is invalid. <p> <dt> <strong>KERN_TERMINATED</strong> <dd> The specified semaphore has been destroyed. <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The semaphore has been signalled. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="semaphore_create.html"><strong>semaphore_create</strong></a>, <a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>, <a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>, \ No newline at end of file +<h2>semaphore_signal_all</h2> +<hr> +<p> +<strong>Function</strong> - Wake up all threads blocked on a semaphore. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t semaphore_signal_all</strong> + <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>semaphore</var> +<dd> +[in send right] The port naming the semaphore to be signalled. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>semaphore_signal_all</strong> function wakes up all of the +threads blocked on the semaphore. The semaphore count is reset to +zero. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The specified semaphore is invalid. +<p> +<dt> <strong>KERN_TERMINATED</strong> +<dd> +The specified semaphore has been destroyed. +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The semaphore has been signalled. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="semaphore_create.html"><strong>semaphore_create</strong></a>, +<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>, +<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>, diff --git a/osfmk/man/semaphore_wait.html b/osfmk/man/semaphore_wait.html index 04a8df9d8..82353a6b6 100755 --- a/osfmk/man/semaphore_wait.html +++ b/osfmk/man/semaphore_wait.html @@ -1 +1,52 @@ -<h2>semaphore_wait</h2> <hr> <p> <strong>Function</strong> - Wait on the specified semaphore. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t semaphore_wait</strong> <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>semaphore</var> <dd> [in send right] The port naming the semaphore that the wait operation is being performed upon. </dl> <h3>DESCRIPTION</h3> <p> The <strong>semaphore_wait</strong> function decrements the semaphore count. If the semaphore count is negative after decrementing, the calling thread blocks. Device driver interrupt service routines (ISR) should never execute <strong>semaphore_wait</strong>, since waiting on a semaphore at the ISR level may, and often will, lead to a deadlock. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> The specified semaphore is invalid. <p> <dt> <strong>KERN_TERMINATED</strong> <dd> The specified semaphore has been destroyed. <p> <dt> <strong>KERN_ABORTED</strong> <dd> The caller was blocked due to a negative count on the semaphore, and was awoken for a reason not related to the semaphore subsystem (e.g. <strong>thread_terminate</strong>). <p> <dt> <strong>KERN_SUCCESS</strong> <dd> The semaphore wait operation was successful. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="semaphore_create.html"><strong>semaphore_create</strong></a>, <a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>, <a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>, <a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>, <a href="device_get_status.html"><strong>device_get_status</strong></a>. \ No newline at end of file +<h2>semaphore_wait</h2> +<hr> +<p> +<strong>Function</strong> - Wait on the specified semaphore. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t semaphore_wait</strong> + <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>semaphore</var> +<dd> +[in send right] The port naming the semaphore that the wait operation is being performed upon. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>semaphore_wait</strong> function decrements the semaphore count. If the +semaphore count is negative after decrementing, the calling thread +blocks. Device driver interrupt service routines (ISR) should never +execute <strong>semaphore_wait</strong>, since waiting on a semaphore at the ISR level +may, and often will, lead to a deadlock. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +The specified semaphore is invalid. +<p> +<dt> <strong>KERN_TERMINATED</strong> +<dd> +The specified semaphore has been destroyed. +<p> +<dt> <strong>KERN_ABORTED</strong> +<dd> +The caller was blocked due to a negative count on the semaphore, and was + awoken for a reason not related to the semaphore subsystem + (e.g. <strong>thread_terminate</strong>). +<p> +<dt> <strong>KERN_SUCCESS</strong> +<dd> +The semaphore wait operation was successful. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="semaphore_create.html"><strong>semaphore_create</strong></a>, +<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>, +<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>, +<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>, +<a href="device_get_status.html"><strong>device_get_status</strong></a>. diff --git a/osfmk/man/seqnos_notify_server.html b/osfmk/man/seqnos_notify_server.html index fadc27a3d..e4ea41d3c 100755 --- a/osfmk/man/seqnos_notify_server.html +++ b/osfmk/man/seqnos_notify_server.html @@ -1 +1,58 @@ -<h2>seqnos_notify_server</h2> <hr> <p> <strong>Function</strong> - Handle the next kernel-generated IPC notification. <h3>SYNOPSIS</h3> <pre> <strong>boolean_t seqnos_notify_server</strong> <strong>(mach_msg_header_t</strong> <var>request_msg</var>, <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>in_msg</var> <dd> [pointer to in structure] The notification message received from the kernel. <p> <dt> <var>out_msg</var> <dd> [out structure] Not used. </dl> <h3>DESCRIPTION</h3> <p> The <strong>seqnos_notify_server</strong> function is the MIG generated server handling function to handle messages from the kernel corresponding to IPC notifications. Such messages are delivered to the notification port named in a <strong>mach_msg</strong> or <strong>mach_port_request_notification</strong> call. The <strong>seqnos_notify_server</strong> function performs all necessary argument handling for this kernel message and calls the appropriate handling function. These functions must be supplied by the caller. <h3>NOTES</h3> <p> <strong>seqnos_notify_server</strong> differs from <strong>notify_server</strong> in that it supplies message sequence numbers to the server interfaces. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>TRUE</strong> <dd> The message was handled and the appropriate function was called. <p> <dt> <strong>FALSE</strong> <dd> The message did not apply to the notification mechanism and no other action was taken. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="notify_server.html"><strong>notify_server<strong></a>, <a href="do_mach_notify_dead_name.html"><strong>do_seqnos_mach_notify_dead_name<strong></a>, <a href="do_mach_notify_no_senders.html"><strong>do_seqnos_mach_notify_no_senders<strong></a>, <a href="DMN_port_deleted.html"><strong>do_seqnos_mach_notify_port_deleted<strong></a>, <a href="do_mach_notify_send_once.html"><strong>do_seqnos_mach_notify_send_once<strong></a>. \ No newline at end of file +<h2>seqnos_notify_server</h2> +<hr> +<p> +<strong>Function</strong> - Handle the next kernel-generated IPC notification. +<h3>SYNOPSIS</h3> +<pre> +<strong>boolean_t seqnos_notify_server</strong> + <strong>(mach_msg_header_t</strong> <var>request_msg</var>, + <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>in_msg</var> +<dd> +[pointer to in structure] +The notification message received from the +kernel. +<p> +<dt> <var>out_msg</var> +<dd> +[out structure] +Not used. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>seqnos_notify_server</strong> function is the MIG generated server handling +function to handle messages from the kernel corresponding to IPC notifications. +Such messages are delivered to the notification port named in a +<strong>mach_msg</strong> or <strong>mach_port_request_notification</strong> call. +The <strong>seqnos_notify_server</strong> function +performs all necessary argument handling for this kernel message and calls the +appropriate handling function. These functions must be supplied by the caller. +<h3>NOTES</h3> +<p> +<strong>seqnos_notify_server</strong> differs from <strong>notify_server</strong> +in that it supplies message +sequence numbers to the server interfaces. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The message was handled and the appropriate function was called. +<p> +<dt> <strong>FALSE</strong> +<dd> +The message did not apply to the notification mechanism and no other +action was taken. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="notify_server.html"><strong>notify_server<strong></a>, +<a href="do_mach_notify_dead_name.html"><strong>do_seqnos_mach_notify_dead_name<strong></a>, +<a href="do_mach_notify_no_senders.html"><strong>do_seqnos_mach_notify_no_senders<strong></a>, +<a href="DMN_port_deleted.html"><strong>do_seqnos_mach_notify_port_deleted<strong></a>, +<a href="do_mach_notify_send_once.html"><strong>do_seqnos_mach_notify_send_once<strong></a>. diff --git a/osfmk/man/task_assign.html b/osfmk/man/task_assign.html index f46671800..6a182ec22 100755 --- a/osfmk/man/task_assign.html +++ b/osfmk/man/task_assign.html @@ -1 +1,49 @@ -<h2>task_assign</h2> <hr> <p> <strong>Function</strong> - Assign a task to a processor set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_assign</strong> <strong>(task_t</strong> <var>task</var>, <strong>processor_set_t</strong> <var>processor_set</var>, <strong>boolean_t</strong> <var>assign_threads</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>task</var> <dd> [in task send right] The port for the task to be assigned. <dt> <var>processor_set</var> <dd> [in processor-set-control send right] The control port for the processor set into which the task is to be assigned. <dt> <var>assign_threads</var> <dd> [in scalar] True if this assignment should apply as well to the threads within the task. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_assign</strong> function assigns <var>task</var> to the set <var>processor_set</var>. After the assignment is completed, newly created threads within this task will be assigned to this processor set. Any previous assignment of the task is nullified. <p> If <var>assign_threads</var> is <strong>TRUE</strong>, existing threads within the task will also be assigned to the processor set. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_assign_default.html"><strong>task_assign_default</strong></a>, <a href="task_get_assignment.html"><strong>task_get_assignment</strong></a>, <a href="processor_set_create.html"><strong>processor_set_create</strong></a>, <a href="processor_set_info.html"><strong>processor_set_info</strong></a>, <a href="thread_assign.html"><strong>thread_assign</strong></a>. \ No newline at end of file +<h2>task_assign</h2> +<hr> +<p> +<strong>Function</strong> - Assign a task to a processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_assign</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>processor_set_t</strong> <var>processor_set</var>, + <strong>boolean_t</strong> <var>assign_threads</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task to be assigned. +<dt> <var>processor_set</var> +<dd> +[in processor-set-control send right] +The control port for the processor +set into which the task is to be assigned. +<dt> <var>assign_threads</var> +<dd> +[in scalar] +True if this assignment should apply as well to the threads +within the task. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_assign</strong> function assigns <var>task</var> to the set +<var>processor_set</var>. +After the assignment is completed, newly created threads within this task +will be assigned to +this processor set. Any previous assignment of the task is nullified. +<p> +If <var>assign_threads</var> is <strong>TRUE</strong>, existing threads within the task +will also be assigned to the processor set. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_assign_default.html"><strong>task_assign_default</strong></a>, +<a href="task_get_assignment.html"><strong>task_get_assignment</strong></a>, +<a href="processor_set_create.html"><strong>processor_set_create</strong></a>, +<a href="processor_set_info.html"><strong>processor_set_info</strong></a>, +<a href="thread_assign.html"><strong>thread_assign</strong></a>. diff --git a/osfmk/man/task_assign_default.html b/osfmk/man/task_assign_default.html index d5b66da69..b45006195 100755 --- a/osfmk/man/task_assign_default.html +++ b/osfmk/man/task_assign_default.html @@ -1 +1,49 @@ -<h2>task_assign_default</h2> <hr> <p> <strong>Function</strong> - Assign a task to the default processor set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_assign_default</strong> <strong>(task_t</strong> <var>task</var>, <strong>boolean_t</strong> <var>assign_threads</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>task</var> <dd> [in task send right] The port for the task to be assigned. <dt> <var>assign_threads</var> <dd> [in scalar] True if this assignment should apply as well to the threads within the task. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_assign_default</strong> function assigns <var>task</var> to the default processor set. After the assignment is completed, newly created threads within this task will be assigned to this processor set. Any previous assignment of the task is nullified. <p> If <var>assign_threads</var> is <strong>TRUE</strong>, existing threads within the task will also be assigned to the processor set. <h3>NOTES</h3> <p> This variant of <strong>task_assign</strong> exists because the control port for the default processor set is privileged, and therefore not available to most tasks. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_assign.html"><strong>task_assign</strong></a>, <a href="task_get_assignment.html"><strong>task_get_assignment</strong></a>, <a href="processor_set_create.html"><strong>processor_set_create</strong></a>, <a href="processor_set_info.html"><strong>processor_set_info</strong></a>, <a href="thread_assign.html"><strong>thread_assign</strong></a>. \ No newline at end of file +<h2>task_assign_default</h2> +<hr> +<p> +<strong>Function</strong> - Assign a task to the default processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_assign_default</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>boolean_t</strong> <var>assign_threads</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task to be assigned. +<dt> <var>assign_threads</var> +<dd> +[in scalar] +True if this assignment should apply as well to the threads +within the task. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_assign_default</strong> function assigns <var>task</var> to the +default processor set. +After the assignment is completed, newly created threads within +this task will be +assigned to this processor set. Any previous assignment of the +task is nullified. +<p> +If <var>assign_threads</var> is <strong>TRUE</strong>, existing threads within the +task will also be assigned to the processor set. +<h3>NOTES</h3> +<p> +This variant of <strong>task_assign</strong> exists because the control +port for the default +processor set is privileged, and therefore not available to most tasks. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_assign.html"><strong>task_assign</strong></a>, +<a href="task_get_assignment.html"><strong>task_get_assignment</strong></a>, +<a href="processor_set_create.html"><strong>processor_set_create</strong></a>, +<a href="processor_set_info.html"><strong>processor_set_info</strong></a>, +<a href="thread_assign.html"><strong>thread_assign</strong></a>. diff --git a/osfmk/man/task_basic_info.html b/osfmk/man/task_basic_info.html index a65b55036..3ca54e793 100755 --- a/osfmk/man/task_basic_info.html +++ b/osfmk/man/task_basic_info.html @@ -1 +1,63 @@ -<h2>task_basic_info</h2> <hr> <p> <strong>Structure</strong> - Defines basic information for a task. <h3>SYNOPSIS</h3> <pre> <strong>struct task_basic_info</strong> <strong>{</strong> <strong>integer_t</strong> <var>suspend_count</var><strong>;</strong> <strong>vm_size_t</strong> <var>virtual_size</var><strong>;</strong> <strong>vm_size_t</strong> <var>resident_size</var><strong>;</strong> <strong>time_value_t</strong> <var>user_time</var><strong>;</strong> <strong>time_value_t</strong> <var>system_time</var><strong>;</strong> <strong>policy_t</strong> <var>policy</var><strong>;</strong> <strong>};</strong> <strong>typedef struct task_basic_info* task_basic_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>suspend_count</var> <dd> The current suspend count for the task. <p> <dt> <var>virtual_size</var> <dd> The number of virtual pages for the task. <p> <dt> <var>resident_size</var> <dd> The number of resident pages for the task <p> <dt> <var>user_time</var> <dd> The total user run time for terminated threads within the task. <p> <dt> <var>system_time</var> <dd> The total system run time for terminated threads within the task. <p> <dt> <var>policy</var> <dd> Default scheduling policy to apply to new threads. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_basic_info</strong> structure defines the basic information array for tasks. The <strong>task_info</strong> function returns this array for a specified task. <h3>NOTES</h3> <p> This structure is machine word length sensitive due to the presence of the virtual address sizes. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_info.html"><strong>task_info</strong></a>. <p> Data Structures: <a href="task_thread_times_info.html"><strong>task_thread_times_info</strong></a>, <a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, <a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, <a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. \ No newline at end of file +<h2>task_basic_info</h2> +<hr> +<p> +<strong>Structure</strong> - Defines basic information for a task. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct task_basic_info</strong> +<strong>{</strong> + <strong>integer_t</strong> <var>suspend_count</var><strong>;</strong> + <strong>vm_size_t</strong> <var>virtual_size</var><strong>;</strong> + <strong>vm_size_t</strong> <var>resident_size</var><strong>;</strong> + <strong>time_value_t</strong> <var>user_time</var><strong>;</strong> + <strong>time_value_t</strong> <var>system_time</var><strong>;</strong> + <strong>policy_t</strong> <var>policy</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct task_basic_info* task_basic_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>suspend_count</var> +<dd> +The current suspend count for the task. + <p> +<dt> <var>virtual_size</var> +<dd> +The number of virtual pages for the task. + <p> +<dt> <var>resident_size</var> +<dd> +The number of resident pages for the task + <p> +<dt> <var>user_time</var> +<dd> +The total user run time for terminated threads within the task. + <p> +<dt> <var>system_time</var> +<dd> +The total system run time for terminated threads within the task. + <p> +<dt> <var>policy</var> +<dd> +Default scheduling policy to apply to new threads. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_basic_info</strong> structure defines the basic information array for +tasks. The <strong>task_info</strong> function returns this array for a specified task. +<h3>NOTES</h3> +<p> +This structure is machine word length sensitive due +to the presence of the +virtual address sizes. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_info.html"><strong>task_info</strong></a>. +<p> +Data Structures: +<a href="task_thread_times_info.html"><strong>task_thread_times_info</strong></a>, +<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, +<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, +<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. diff --git a/osfmk/man/task_create.html b/osfmk/man/task_create.html index 0cdc648a4..7578a8e06 100755 --- a/osfmk/man/task_create.html +++ b/osfmk/man/task_create.html @@ -1 +1,124 @@ -<h2>task_create</h2> <hr> <p> <strong>Function</strong> - Create a new task. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_create</strong> <strong>(task_t</strong> <var>parent_task</var>, <strong>ledger_port_array_t</strong> <var>ledgers</var>, <strong>int</strong> <var>ledger_count</var>, <strong>boolean_t</strong> <var>inherit_memory</var>, <strong>task_t</strong> <var>child_task</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>parent_task</var> <dd> [in task send right] The port for the task from which to draw the child task's port rights and address space. <p> <dt> <var>ledgers</var> <dd> [pointer to in array of ledger send rights] Resource ledgers (on the destination host) from which the task will draw its resources. The first element of this array is the wired kernel ledger, the second the paged space ledger. If the number of ledgers supplied does not match the required number or one or more is null, the parent task's ledger is used. <p> <dt> <var>ledger_count</var> <dd> [in scalar] The number of ledger ports in the <var>ledgers</var> array. <p> <dt> <var>inherit_memory</var> <dd> [in scalar] Address space inheritance indicator. If true, the child task inherits the (inheritable) address space of the parent task. If false, the kernel assigns the child task an empty address space. <p> <dt> <var>child_task</var> <dd> [out task send right] The kernel-assigned port for the new task. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_create</strong> function creates a new task from <var>parent_task</var> and returns the name of the new task in <var>child_task</var>. The child task acquires shared or copied parts of the parent's address space (see <strong>vm_inherit</strong>). The child task initially contains no threads. The child task inherits the parent's security ID. <p> The child task receives the following "special" ports, which are created or copied for it at task creation: <dl> <dt> [task-self send right] <dd> The port by which the kernel knows the new child task and allows it to be manipulated. The child task holds a send right for this port. The port name is also returned to the calling task. <p> <dt> [bootstrap send right] <dd> The port to which the child task can send a message requesting return of any system service ports that it needs (for example, a port to the Network Name Server or the Environment Manager). The child task inherits a send right for this port from the parent task. The task can use <strong>task_set_special_port</strong> to change this port. <p> <dt> [host-self send right] <dd> The port by which the child task requests information about its host. The child task inherits a send right for this port from the parent task. <p> <dt> [ledger send rights] <dd> The ports naming the ledgers from which the task draws its resources. </dl> <p> The child task also inherits the following ports: <dl> <dt> [sample send right] <dd> The port to which PC sampling messages are to be sent. <p> <dt> [exception send rights] <dd> Ports to which exception messages are sent. <p> <dt> [registered send rights] <dd> Ports to system services. </dl> <h3>NOTES</h3> <p> The <strong>ledgers</strong> functionality mentioned above is not currently implemented. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create_security_token.html"><strong>task_create_security_token</strong></a>, <a href="task_resume.html"><strong>task_resume</strong></a>, <a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>, <a href="task_suspend.html"><strong>task_suspend</strong></a>, <a href="task_terminate.html"><strong>task_terminate</strong></a>, <a href="task_threads.html"><strong>task_threads</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_resume.html"><strong>thread_resume</strong></a>, <a href="vm_inherit.html"><strong>vm_inherit</strong></a>, <a href="task_sample.html"><strong>task_sample</strong></a>, <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, <a href="mach_ports_register.html"><strong>mach_ports_register</strong></a>, <a href="norma_task_create.html"><strong>norma_task_create</strong></a>, <a href="host_security_set_task_token.html"><strong>host_security_set_task_token</strong></a>. \ No newline at end of file +<h2>task_create</h2> +<hr> +<p> +<strong>Function</strong> - Create a new task. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_create</strong> + <strong>(task_t</strong> <var>parent_task</var>, + <strong>ledger_port_array_t</strong> <var>ledgers</var>, + <strong>int</strong> <var>ledger_count</var>, + <strong>boolean_t</strong> <var>inherit_memory</var>, + <strong>task_t</strong> <var>child_task</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>parent_task</var> +<dd> +[in task send right] +The port for the task from which to draw the child +task's port rights and address space. +<p> +<dt> <var>ledgers</var> +<dd> +[pointer to in array of ledger send rights] +Resource ledgers (on the +destination host) from which the task will draw its resources. The first +element of this array is the wired kernel ledger, the second the paged +space ledger. If the number of ledgers supplied does not match the +required number or one or more is null, the parent task's ledger is used. +<p> +<dt> <var>ledger_count</var> +<dd> +[in scalar] +The number of ledger ports in the <var>ledgers</var> array. +<p> +<dt> <var>inherit_memory</var> +<dd> +[in scalar] +Address space inheritance indicator. If true, the child task +inherits the (inheritable) address space of the parent task. If false, the +kernel assigns the child task an empty address space. +<p> +<dt> <var>child_task</var> +<dd> +[out task send right] +The kernel-assigned port for the new task. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_create</strong> function creates a new task from <var>parent_task</var> +and returns the name of the new task in <var>child_task</var>. +The child task acquires shared or copied parts of the parent's address space +(see <strong>vm_inherit</strong>). The child task initially +contains no threads. The child task inherits the parent's security ID. +<p> +The child task receives the following "special" ports, which are created or +copied for it at task creation: +<dl> +<dt> [task-self send right] +<dd> +The port by which the kernel knows the new child task +and allows it to be manipulated. The child task holds a send right for this +port. The port name is also returned to the calling task. +<p> +<dt> [bootstrap send right] +<dd> +The port to which the child task can send a message +requesting return of any system service ports that it needs (for +example, a port +to the Network Name Server or the Environment Manager). The child task +inherits a send right for this port from the parent task. The task can use +<strong>task_set_special_port</strong> to change this port. +<p> +<dt> [host-self send right] +<dd> +The port by which the child task requests information +about its host. The child task inherits a send right for this port from the +parent task. +<p> +<dt> [ledger send rights] +<dd> +The ports naming the ledgers from which the task draws +its resources. +</dl> +<p> +The child task also inherits the following ports: +<dl> +<dt> [sample send right] +<dd> +The port to which PC sampling messages are to be sent. +<p> +<dt> [exception send rights] +<dd> +Ports to which exception messages are sent. +<p> +<dt> [registered send rights] +<dd> +Ports to system services. +</dl> +<h3>NOTES</h3> +<p> +The <strong>ledgers</strong> functionality mentioned above is not +currently implemented. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create_security_token.html"><strong>task_create_security_token</strong></a>, +<a href="task_resume.html"><strong>task_resume</strong></a>, +<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>, +<a href="task_suspend.html"><strong>task_suspend</strong></a>, +<a href="task_terminate.html"><strong>task_terminate</strong></a>, +<a href="task_threads.html"><strong>task_threads</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_resume.html"><strong>thread_resume</strong></a>, +<a href="vm_inherit.html"><strong>vm_inherit</strong></a>, +<a href="task_sample.html"><strong>task_sample</strong></a>, +<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, +<a href="mach_ports_register.html"><strong>mach_ports_register</strong></a>, +<a href="norma_task_create.html"><strong>norma_task_create</strong></a>, +<a href="host_security_set_task_token.html"><strong>host_security_set_task_token</strong></a>. diff --git a/osfmk/man/task_get_assignment.html b/osfmk/man/task_get_assignment.html index 4cdaecff4..298ed5747 100755 --- a/osfmk/man/task_get_assignment.html +++ b/osfmk/man/task_get_assignment.html @@ -1 +1,39 @@ -<h2>task_get_assignment</h2> <hr> <p> <strong>Function</strong> - Return the processor set to which a task is assigned. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_get_assignment</strong> <strong>(task_t</strong> <var>task</var>, <strong>processor_set_name_t</strong> <var>processor_set</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>task</var> <dd> [in task send right] The port for the task whose assignment is desired. <dt> <var>processor_set</var> <dd> [out processor-set-name send right] The name port for the processor set into which the task is assigned. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_get_assignment</strong> function returns the name port to the processor set to which <var>task</var> is currently assigned. This port can only be used to obtain information about the processor set. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_assign.html"><strong>task_assign</strong></a>, <a href="task_assign_default.html"><strong>task_assign_default</strong></a>, <a href="processor_set_create.html"><strong>processor_set_create</strong></a>, <a href="processor_set_info.html"><strong>processor_set_info</strong></a>, <a href="thread_assign.html"><strong>thread_assign</strong></a>. \ No newline at end of file +<h2>task_get_assignment</h2> +<hr> +<p> +<strong>Function</strong> - Return the processor set to which a task is assigned. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_get_assignment</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>processor_set_name_t</strong> <var>processor_set</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task whose assignment is desired. +<dt> <var>processor_set</var> +<dd> +[out processor-set-name send right] +The name port for the processor +set into which the task is assigned. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_get_assignment</strong> function returns the name port +to the processor set to +which <var>task</var> is currently assigned. This port can only be used to obtain +information about the processor set. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_assign.html"><strong>task_assign</strong></a>, +<a href="task_assign_default.html"><strong>task_assign_default</strong></a>, +<a href="processor_set_create.html"><strong>processor_set_create</strong></a>, +<a href="processor_set_info.html"><strong>processor_set_info</strong></a>, +<a href="thread_assign.html"><strong>thread_assign</strong></a>. diff --git a/osfmk/man/task_get_emulation_vector.html b/osfmk/man/task_get_emulation_vector.html index 46281cdb3..e6beed728 100755 --- a/osfmk/man/task_get_emulation_vector.html +++ b/osfmk/man/task_get_emulation_vector.html @@ -1 +1,54 @@ -<h2>task_get_emulation_vector</h2> <hr> <p> <strong>Function</strong> - Return an array identifying the target task's user-level system call handlers. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_get_emulation_vector</strong> <strong>(task_t</strong> <var>task</var>, <strong>int</strong> <var>vector_start</var>, <strong>emulation_vector_t</strong> <var>emulation_vector</var>, <strong>mach_msg_type_number_t*</strong> <var>emulation_vector_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The port for the task for which the system call handler addresses are desired. <p> <dt> <var>vector_start</var> <dd> [out scalar] The syscall number corresponding to the first element of <var>emulation_vector</var>. <p> <dt> <var>emulation_vector</var> <dd> [out pointer to dynamic array of <strong>vm_address_t</strong>] Pointer to the returned array of routine entrypoints for the system calls starting with syscall number <var>vector_start</var>. <p> <dt> <var>emulation_vector_count</var> <dd> [out scalar] The number of entries filled by the kernel. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_get_emulation_vector</strong> function returns the user-level syscall handler entrypoint addresses. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual addresses in the <var>emulation_vector</var> parameter. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_set_emulation_vector.html"><strong>task_set_emulation_vector</strong></a>. \ No newline at end of file +<h2>task_get_emulation_vector</h2> +<hr> +<p> +<strong>Function</strong> - Return an array identifying the target task's user-level system call handlers. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_get_emulation_vector</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>int</strong> <var>vector_start</var>, + <strong>emulation_vector_t</strong> <var>emulation_vector</var>, + <strong>mach_msg_type_number_t*</strong> <var>emulation_vector_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task for which the system call +handler addresses are desired. +<p> +<dt> <var>vector_start</var> +<dd> +[out scalar] +The syscall number corresponding to the first element of +<var>emulation_vector</var>. +<p> +<dt> <var>emulation_vector</var> +<dd> +[out pointer to dynamic array of <strong>vm_address_t</strong>] +Pointer to the returned +array of routine entrypoints for the system calls starting with syscall +number <var>vector_start</var>. +<p> +<dt> <var>emulation_vector_count</var> +<dd> +[out scalar] +The number of entries filled by the kernel. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_get_emulation_vector</strong> function returns the +user-level syscall handler entrypoint addresses. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the +virtual addresses in the <var>emulation_vector</var> parameter. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_set_emulation_vector.html"><strong>task_set_emulation_vector</strong></a>. diff --git a/osfmk/man/task_get_exception_ports.html b/osfmk/man/task_get_exception_ports.html index 31da03ec0..c11f4c2c8 100755 --- a/osfmk/man/task_get_exception_ports.html +++ b/osfmk/man/task_get_exception_ports.html @@ -1 +1,140 @@ -<h2>task_get_exception_ports</h2> <hr> <p> <strong>Function</strong> - Return send rights to the target task's exception ports. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_get_exception_ports</strong> <strong>(task_t</strong> <var>task</var>, <strong>exception_mask_t</strong> <var>exception_types</var>, <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>, <strong>old_exception_masks</strong> <var>old_exception_count</var>, <strong>exception_port_array_t</strong> <var>old_exception_ports</var>, <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>, <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task for which to return the exception ports. <p> <dt> <var>exception_types</var> <dd> [in scalar] A flag word indicating the types of exceptions for which the exception ports are desired: <dl> <p> <dt> <strong>EXC_MASK_BAD_ACCESS</strong> <dd> Could not access memory. <p> <dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> <dd> Instruction failed. Illegal or undefined instruction or operand. <p> <dt> <strong>EXC_MASK_ARITHMETIC</strong> <dd> Arithmetic exception <p> <dt> <strong>EXC_MASK_EMULATION</strong> <dd> Emulation instruction. Emulation support instruction encountered. <p> <dt> <strong>EXC_MASK_SOFTWARE</strong> <dd> Software generated exception. <p> <dt> <strong>EXC_MASK_BREAKPOINT</strong> <dd> Trace, breakpoint, etc. <p> <dt> <strong>EXC_MASK_SYSCALL</strong> <dd> System call requested. <p> <dt> <strong>EXC_MASK_MACH_SYSCALL</strong> <dd> System call with a number in the Mach call range requested. <p> <dt> <strong>EXC_MASK_RPC_ALERT </strong> <dd> Exceptional condition encountered during execution of RPC. </dl> <p> <dt> <var>old_exception_masks</var> <dd> [out array of <var>exception_mask_t</var>] An array, each element being a mask specifying for which exception types the corresponding element of the other arrays apply. <p> <dt> <var>old_exception_count</var> <dd> [pointer to in/out scalar] On input, the maximum size of the array buffers; on output, the number of returned <exception type mask, exception port, behavior, flavor> sets returned. <p> <dt> <var>old_exception_ports</var> <dd> [out array of exception send rights] The returned exception ports. <p> <dt> <var>old_behaviors</var> <dd> [out array of <var>exception_behavior_t</var>] The type of exception message to be sent. Defined types are: <dl> <p> <dt> <strong>EXCEPTION_DEFAULT</strong> <dd> Send a <strong>catch_exception_raise</strong> message including the thread identity. <p> <dt> <strong>EXCEPTION_STATE</strong> <dd> Send a <strong>catch_exception_raise_state</strong> message including the thread state. <p> <dt> <strong>EXCEPTION_STATE_IDENTITY</strong> <dd> Send a <strong>catch_exception_raise_state_identity</strong> message including the thread identity and state. </dl> <p> <dt> <var>old_flavors</var> <dd> [out array of <var>thread_state_flavor_t</var>] The type of state to be sent with the exception message. These types are defined in <strong><mach/thread_states.h></strong>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_get_exception_ports</strong> function returns send rights for a specified set of exception ports belonging to task. A task exception port is used when a thread specific exception port returns a non-success reply. The call returns a set of quadruples <exception type mask, exception port, behavior, flavor> for each unique set of <exception port, behavior, flavor> in effect for the task where the exception type mask indicates for which exception types the other values apply. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_task_self.html"><strong>mach_task_self</strong></a>, <a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, <a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, <a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, <a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>. \ No newline at end of file +<h2>task_get_exception_ports</h2> +<hr> +<p> +<strong>Function</strong> - Return send rights to the target task's exception ports. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_get_exception_ports</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>exception_mask_t</strong> <var>exception_types</var>, + <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>, + <strong>old_exception_masks</strong> <var>old_exception_count</var>, + <strong>exception_port_array_t</strong> <var>old_exception_ports</var>, + <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>, + <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task for which to return the exception ports. +<p> +<dt> <var>exception_types</var> +<dd> +[in scalar] +A flag word indicating the types of exceptions for which the +exception ports are desired: +<dl> +<p> +<dt> <strong>EXC_MASK_BAD_ACCESS</strong> +<dd> +Could not access memory. +<p> +<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> +<dd> +Instruction failed. Illegal or undefined instruction or operand. +<p> +<dt> <strong>EXC_MASK_ARITHMETIC</strong> +<dd> +Arithmetic exception +<p> +<dt> <strong>EXC_MASK_EMULATION</strong> +<dd> +Emulation instruction. Emulation support instruction +encountered. +<p> +<dt> <strong>EXC_MASK_SOFTWARE</strong> +<dd> +Software generated exception. +<p> +<dt> <strong>EXC_MASK_BREAKPOINT</strong> +<dd> +Trace, breakpoint, etc. +<p> +<dt> <strong>EXC_MASK_SYSCALL</strong> +<dd> +System call requested. +<p> +<dt> <strong>EXC_MASK_MACH_SYSCALL</strong> +<dd> +System call with a number in the Mach call range requested. +<p> +<dt> <strong>EXC_MASK_RPC_ALERT </strong> +<dd> +Exceptional condition encountered during execution of RPC. +</dl> +<p> +<dt> <var>old_exception_masks</var> +<dd> +[out array of <var>exception_mask_t</var>] +An array, each element being a mask +specifying for which exception types the corresponding element of the +other arrays apply. +<p> +<dt> <var>old_exception_count</var> +<dd> +[pointer to in/out scalar] +On input, the maximum size of the array +buffers; on output, the number of returned <exception type mask, +exception port, behavior, flavor> sets returned. +<p> +<dt> <var>old_exception_ports</var> +<dd> +[out array of exception send rights] +The returned exception ports. +<p> +<dt> <var>old_behaviors</var> +<dd> +[out array of <var>exception_behavior_t</var>] +The type of exception message to +be sent. Defined types are: +<dl> +<p> +<dt> <strong>EXCEPTION_DEFAULT</strong> +<dd> +Send a <strong>catch_exception_raise</strong> message including the thread identity. +<p> +<dt> <strong>EXCEPTION_STATE</strong> +<dd> +Send a <strong>catch_exception_raise_state</strong> message including the +thread state. +<p> +<dt> <strong>EXCEPTION_STATE_IDENTITY</strong> +<dd> +Send a <strong>catch_exception_raise_state_identity</strong> message +including the thread identity and state. +</dl> +<p> +<dt> <var>old_flavors</var> +<dd> +[out array of <var>thread_state_flavor_t</var>] +The type of state to be sent with +the exception message. These types are defined in <strong><mach/thread_states.h></strong>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_get_exception_ports</strong> function returns send +rights for a specified set +of exception ports belonging to task. A task exception port is used when a +thread specific exception port returns a non-success reply. +The call returns a set +of quadruples <exception type mask, exception port, behavior, flavor> for each +unique set of <exception port, behavior, flavor> in effect for +the task where the +exception type mask indicates for which exception types the other values apply. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_task_self.html"><strong>mach_task_self</strong></a>, +<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, +<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, +<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, +<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, +<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>. diff --git a/osfmk/man/task_get_special_port.html b/osfmk/man/task_get_special_port.html index 589e644e8..9ff80bc28 100755 --- a/osfmk/man/task_get_special_port.html +++ b/osfmk/man/task_get_special_port.html @@ -1 +1,104 @@ -<h2>task_get_special_port</h2> <hr> <p> <strong>Function</strong> - Return a send write to the indicated special port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_get_special_port</strong> <strong>(task_t</strong> <var>task</var>, <strong>int</strong> <var>which_port</var>, <strong>task</strong> <var>special_port</var><strong>);</strong> <strong>Macro Forms:</strong> <strong>kern_return_t task_get_bootstrap_port</strong> <strong>(task_t</strong> <var>task</var>, <strong>task</strong> <var>special_port</var><strong>);</strong> <strong>kern_return_t task_get_kernel_port</strong> <strong>(task_t</strong> <var>task</var>, <strong>task</strong> <var>special_port</var><strong>);</strong> <strong>kern_return_t task_get_host_name_port</strong> <strong>(task_t</strong> <var>task</var>, <strong>task</strong> <var>special_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The port for the task for which to return the port's send right. <p> <dt> <var>which_port</var> <dd> [in scalar] The special port for which the send right is requested. Valid values are: <dl> <p> <dt> <strong>TASK_KERNEL_PORT</strong> <dd> [task-self send right] The port used to control this task. Used to send messages that affect the task. This is the port returned by <strong>mach_task_self</strong>. <p> <dt> <strong>TASK_BOOTSTRAP_PORT</strong> <dd> [bootstrap send right] The task's bootstrap port. Used to send messages requesting return of other system service ports. <p> <dt> <strong>TASK_HOST_NAME_PORT</strong> <dd> [host-self send right] The port used to request information of the containing host. This is the port returned by <strong>mach_host_self</strong>. <p> <dt> <strong>TASK_WIRED_LEDGER_PORT</strong> <dd> [ledger send right] The port naming the source from which this task draws its wired kernel memory. <p> <dt> <strong>TASK_PAGED_LEDGER_PORT</strong> <dd> [ledger send right] The port naming the source from which this task draws its default memory managed memory. </dl> <p> <dt> <var>special_port</var> <dd> [out task-special send right] The returned value for the port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_get_special_port</strong> function returns a send right for a special port belonging to <var>task</var>. <p> If one task has a send right for the kernel port of another task, it can use the port to perform kernel operations for the other task. Send rights for a kernel port normally are held only by the task to which the port belongs, or by the task's parent task. Using the <strong>mach_msg</strong> function, however, any task can pass a send right for its kernel port to another task. <h3>NOTES</h3> <p> The current implementation does not support the <strong>TASK_HOST_NAME_PORT</strong> features associated with this interface. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_task_self.html"><strong>mach_task_self</strong></a>, <a href="task_create.html"><strong>task_create</strong></a>, <a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>, <a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>, <a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>, <a href="mach_host_self.html"><strong>mach_host_self</strong></a>. \ No newline at end of file +<h2>task_get_special_port</h2> +<hr> +<p> +<strong>Function</strong> - Return a send write to the indicated special port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_get_special_port</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>int</strong> <var>which_port</var>, + <strong>task</strong> <var>special_port</var><strong>);</strong> + + +<strong>Macro Forms:</strong> + + +<strong>kern_return_t task_get_bootstrap_port</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>task</strong> <var>special_port</var><strong>);</strong> + + +<strong>kern_return_t task_get_kernel_port</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>task</strong> <var>special_port</var><strong>);</strong> + + +<strong>kern_return_t task_get_host_name_port</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>task</strong> <var>special_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task for which to return the port's +send right. +<p> +<dt> <var>which_port</var> +<dd> +[in scalar] +The special port for which the send right is requested. Valid +values are: +<dl> +<p> +<dt> <strong>TASK_KERNEL_PORT</strong> +<dd> +[task-self send right] The port used to control this task. Used +to send messages that affect the task. This is the port returned +by <strong>mach_task_self</strong>. +<p> +<dt> <strong>TASK_BOOTSTRAP_PORT</strong> +<dd> +[bootstrap send right] The task's bootstrap port. Used to send +messages requesting return of other system service ports. +<p> +<dt> <strong>TASK_HOST_NAME_PORT</strong> +<dd> +[host-self send right] The port used to request information of +the containing host. This is the port returned by +<strong>mach_host_self</strong>. +<p> +<dt> <strong>TASK_WIRED_LEDGER_PORT</strong> +<dd> +[ledger send right] The port naming the source from which +this task draws its wired kernel memory. +<p> +<dt> <strong>TASK_PAGED_LEDGER_PORT</strong> +<dd> +[ledger send right] The port naming the source from which +this task draws its default memory managed memory. +</dl> +<p> +<dt> <var>special_port</var> +<dd> +[out task-special send right] +The returned value for the port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_get_special_port</strong> function returns a send right +for a special port belonging to <var>task</var>. +<p> +If one task has a send right for the kernel port of another task, it can use +the port to perform kernel operations for the other task. Send rights for a +kernel port normally are held only by the task to which the port belongs, +or by the task's parent task. Using the <strong>mach_msg</strong> function, however, +any task can pass a send right for its kernel port to another task. +<h3>NOTES</h3> +<p> +The current implementation does not support the <strong>TASK_HOST_NAME_PORT</strong> +features associated with this interface. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_task_self.html"><strong>mach_task_self</strong></a>, +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>, +<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>, +<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>, +<a href="mach_host_self.html"><strong>mach_host_self</strong></a>. diff --git a/osfmk/man/task_info.html b/osfmk/man/task_info.html index 5fa772bc3..cf06661f2 100755 --- a/osfmk/man/task_info.html +++ b/osfmk/man/task_info.html @@ -1 +1,117 @@ -<h2>task_info</h2> <hr> <p> <strong>Function</strong> - Return per-task information according to specified flavor. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_info</strong> <strong>(task_t</strong> <var>task</var>, <strong>task_flavor_t</strong> <var>flavor</var>, <strong>task_info_t</strong> <var>task_info</var>, <strong>mach_msg_type_number_t</strong> <var>task_info_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The port for the task for which the information is to be returned. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of information to be returned. Valid values are: <dl> <p> <dt> <strong>TASK_BASIC_INFO</strong> <dd> Returns basic information about the task, such as the task's suspend count and number of resident pages. The structure returned is <strong>task_basic_info</strong>. <p> <dt> <strong>TASK_THREAD_TIMES_INFO</strong> <dd> Returns system and user space run-times for live threads. The structure returned is <strong>task_thread_times_info</strong>. <p> <dt> <strong>TASK_SCHED_FIFO_INFO</strong> <dd> Returns default <strong>FIFO</strong> scheduling policy attributes to be assigned to new threads. The structure returned is <strong>policy_fifo_base</strong>. <p> <dt> <strong>TASK_SCHED_RR_INFO</strong> <dd> Returns default round-robin scheduling policy attributes to be assigned to new threads. The structure returned is <strong>policy_rr_base</strong>. <p> <dt> <strong>TASK_SCHED_TIMESHARE_INFO</strong> <dd> Returns default timeshare scheduling policy attributes to be assigned to new threads. The structure returned is <strong>policy_timeshare_base</strong>. <p> <dt> <strong>TASK_SECURITY_TOKEN</strong> <dd> Returns the security token for the task. The value returned is of type <var>security_token_t</var>. <p> <dt> <strong>TASK_AUDIT_TOKEN</strong> <dd> Returns the security token for the task. The value returned is of type <var>audit_token_t</var>. <p> <dt> <strong>TASK_USER_DATA</strong> <dd> Returns user-specified information previously established via the <strong>task_set_info</strong> interface. The structure returned is <strong>task_user_data</strong>. </dl> <p> <dt> <var>task_info</var> <dd> [out structure] Information about the specified task. <p> <dt> <var>task_info_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_info</strong> function returns an information structure of type <var>flavor</var>. <h3>NOTES</h3> <p> At any given time, a task has one default scheduling policy assigned to it (as returned by <strong>TASK_BASIC_INFO</strong>). As such, only one of the scheduling flavors will return valid information. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_POLICY</strong> <dd> A request was made for the default scheduling policy attributes for the task but the requested policy is not the task's default policy. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>, <a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>, <a href="task_set_info.html"><strong>task_set_info</strong></a>, <a href="task_threads.html"><strong>task_threads</strong></a>, <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="thread_get_state.html"><strong>thread_get_state</strong></a>, <a href="thread_set_state.html"><strong>thread_set_state</strong></a>. <p> Data Structures: <a href="task_basic_info.html"><strong>task_basic_info</strong></a>, <a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>, <a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, <a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, <a href="task_thread_times_info.html"><strong>task_thread_times_info</strong></a>. \ No newline at end of file +<h2>task_info</h2> +<hr> +<p> +<strong>Function</strong> - Return per-task information according to specified flavor. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_info</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>task_flavor_t</strong> <var>flavor</var>, + <strong>task_info_t</strong> <var>task_info</var>, + <strong>mach_msg_type_number_t</strong> <var>task_info_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task for which the information is to +be returned. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of information to be returned. Valid values are: +<dl> +<p> +<dt> <strong>TASK_BASIC_INFO</strong> +<dd> +Returns basic information about the task, such as the task's +suspend count and number of resident pages. The structure +returned is <strong>task_basic_info</strong>. +<p> +<dt> <strong>TASK_THREAD_TIMES_INFO</strong> +<dd> +Returns system and user space run-times for live threads. The +structure returned is <strong>task_thread_times_info</strong>. +<p> +<dt> <strong>TASK_SCHED_FIFO_INFO</strong> +<dd> +Returns default <strong>FIFO</strong> scheduling policy attributes to be +assigned to new threads. The structure returned is <strong>policy_fifo_base</strong>. +<p> +<dt> <strong>TASK_SCHED_RR_INFO</strong> +<dd> +Returns default round-robin scheduling policy attributes to be +assigned to new threads. The structure returned is +<strong>policy_rr_base</strong>. +<p> +<dt> <strong>TASK_SCHED_TIMESHARE_INFO</strong> +<dd> +Returns default timeshare scheduling policy attributes to be +assigned to new threads. The structure returned is +<strong>policy_timeshare_base</strong>. +<p> +<dt> <strong>TASK_SECURITY_TOKEN</strong> +<dd> +Returns the security token for the task. The value returned is of +type <var>security_token_t</var>. +<p> +<dt> <strong>TASK_AUDIT_TOKEN</strong> +<dd> +Returns the security token for the task. The value returned is of +type <var>audit_token_t</var>. +<p> +<dt> <strong>TASK_USER_DATA</strong> +<dd> +Returns user-specified information previously established via the +<strong>task_set_info</strong> interface. The structure returned is +<strong>task_user_data</strong>. +</dl> +<p> +<dt> <var>task_info</var> +<dd> +[out structure] +Information about the specified task. +<p> +<dt> <var>task_info_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_info</strong> function returns an information structure +of type <var>flavor</var>. +<h3>NOTES</h3> +<p> +At any given time, a task has one default scheduling policy assigned to it (as +returned by <strong>TASK_BASIC_INFO</strong>). As such, only one of the scheduling flavors +will return valid information. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_POLICY</strong> +<dd> +A request was made for the default scheduling policy attributes for the +task but the requested policy is not the task's default policy. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>, +<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>, +<a href="task_set_info.html"><strong>task_set_info</strong></a>, +<a href="task_threads.html"><strong>task_threads</strong></a>, +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, +<a href="thread_set_state.html"><strong>thread_set_state</strong></a>. +<p> +Data Structures: +<a href="task_basic_info.html"><strong>task_basic_info</strong></a>, +<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>, +<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, +<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, +<a href="task_thread_times_info.html"><strong>task_thread_times_info</strong></a>. diff --git a/osfmk/man/task_policy.html b/osfmk/man/task_policy.html index 1e3535b03..7b71ec043 100755 --- a/osfmk/man/task_policy.html +++ b/osfmk/man/task_policy.html @@ -1 +1,75 @@ -<h2>task_policy</h2> <hr> <p> <strong>Function</strong> - Set target task's default scheduling policy state. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_policy</strong> <strong>(task_t</strong> <var>task</var>, <strong>policy_t</strong> <var>policy</var>, <strong>policy_base_t</strong> <var>base</var>, <strong>base</strong> <var>base_count</var>, <strong>boolean_t</strong> <var>set_limit</var>, <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>task</var> <dd> [in task send right] The port for the task whose scheduling attributes are to be set. <dt> <var>policy</var> <dd> [in scalar] Default policy. The values currently defined are <strong>POLICY_TIMESHARE</strong>, <strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out). <dt> <var>base</var> <dd> [pointer to in structure] Base scheduling policy data, <strong>policy_fifo_base</strong>, <strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>. <dt> <var>base_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). <dt> <var>set_limit</var> <dd> [in scalar] True if the scheduling limits for the task should be restricted to allow no more service than specified by <var>base</var>. <dt> <var>change_threads</var> <dd> [in scalar] True if the attributes (and limits, if <var>set_limit</var> is true) of existing threads within the task should also be changed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_policy</strong> function sets the default scheduling attributes for <var>task</var>. These attributes are used when creating new threads. Changing the default attributes for a task does not affect the attributes of the contained threads unless <var>change_threads</var> is <strong>TRUE</strong>. At no time will a thread ever have scheduling attributes that exceed the thread's limits. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_INVALID_POLICY</strong> <dd> The processor set does not currently enable <var>policy</var>. <dt> <strong>KERN_POLICY_LIMIT</strong> <dd> The specified scheduling attributes exceeds the thread's limits. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_policy.html"><strong>thread_policy</strong></a>, <a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>, <a href="task_set_policy.html"><strong>task_set_policy</strong></a>, <a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>. <p> Data Structures: <a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, <a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, <a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. \ No newline at end of file +<h2>task_policy</h2> +<hr> +<p> +<strong>Function</strong> - Set target task's default scheduling policy state. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_policy</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>policy_t</strong> <var>policy</var>, + <strong>policy_base_t</strong> <var>base</var>, + <strong>base</strong> <var>base_count</var>, + <strong>boolean_t</strong> <var>set_limit</var>, + <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task whose scheduling attributes +are to be set. +<dt> <var>policy</var> +<dd> +[in scalar] +Default policy. The values currently defined are <strong>POLICY_TIMESHARE</strong>, +<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out). +<dt> <var>base</var> +<dd> +[pointer to in structure] +Base scheduling policy data, <strong>policy_fifo_base</strong>, +<strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>. +<dt> <var>base_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +<dt> <var>set_limit</var> +<dd> +[in scalar] +True if the scheduling limits for the task should be restricted +to allow no more service than specified by <var>base</var>. +<dt> <var>change_threads</var> +<dd> +[in scalar] +True if the attributes (and limits, if <var>set_limit</var> is true) of +existing threads within the task should also be changed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_policy</strong> function sets the default scheduling +attributes for <var>task</var>. These +attributes are used when creating new threads. Changing the default attributes +for a task does not affect the attributes of the contained threads unless +<var>change_threads</var> is <strong>TRUE</strong>. At no time will a thread ever have +scheduling attributes that exceed the thread's limits. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>KERN_INVALID_POLICY</strong> +<dd> +The processor set does not currently enable <var>policy</var>. +<dt> <strong>KERN_POLICY_LIMIT</strong> +<dd> +The specified scheduling attributes exceeds the thread's limits. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_policy.html"><strong>thread_policy</strong></a>, +<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>, +<a href="task_set_policy.html"><strong>task_set_policy</strong></a>, +<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>. +<p> +Data Structures: +<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, +<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, +<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. diff --git a/osfmk/man/task_resume.html b/osfmk/man/task_resume.html index 78fcdf022..7eb73e40b 100755 --- a/osfmk/man/task_resume.html +++ b/osfmk/man/task_resume.html @@ -1 +1,39 @@ -<h2>task_resume</h2> <hr> <p> <strong>Function</strong> - Decrement the target task's suspend count. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_resume</strong> <strong>(task_t</strong> <var>task</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The port to the task to be resumed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_resume</strong> function decrements the suspend count for <var>task</var>. If the task's suspend count goes to zero, the function resumes any suspended threads within the task. To resume a given thread, the thread's own suspend count must also be zero. <h3>NOTES</h3> <p> An attempt to lower the suspend count below zero is ignored. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="task_info.html"><strong>task_info</strong></a>, <a href="task_suspend.html"><strong>task_suspend</strong></a>, <a href="task_terminate.html"><strong>task_terminate</strong></a>, <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="thread_resume.html"><strong>thread_resume</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>. \ No newline at end of file +<h2>task_resume</h2> +<hr> +<p> +<strong>Function</strong> - Decrement the target task's suspend count. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_resume</strong> + <strong>(task_t</strong> <var>task</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The port to the task to be resumed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_resume</strong> function decrements the suspend count +for <var>task</var>. If the task's suspend count goes to zero, the +function resumes any suspended threads within the task. To resume +a given thread, the thread's own suspend count must also be zero. +<h3>NOTES</h3> +<p> +An attempt to lower the suspend count below zero is ignored. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="task_suspend.html"><strong>task_suspend</strong></a>, +<a href="task_terminate.html"><strong>task_terminate</strong></a>, +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="thread_resume.html"><strong>thread_resume</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>. diff --git a/osfmk/man/task_sample.html b/osfmk/man/task_sample.html index ab5e9dc24..829e47045 100755 --- a/osfmk/man/task_sample.html +++ b/osfmk/man/task_sample.html @@ -1 +1,41 @@ -<h2>task_sample</h2> <hr> <p> <strong>Function</strong> - Sample the target task's thread program counters periodically. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_sample</strong> <strong>(task_t</strong> <var>sample_task</var>, <strong>mach_port_make_send_t</strong> <var>reply_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>sample_task</var> <dd> [in task send right] Port for the task whose threads' PC are to be sampled. <p> <dt> <var>reply_port</var> <dd> [in sample receive (to be converted to send) right] Port to which PC sample buffers are sent. A value of <strong>MACH_PORT_NULL</strong> stops PC sampling for the task. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_sample</strong> function causes the program counter (PC) of the specified <var>sample_task</var> (actually, all of the threads within <var>sample_task</var>) to be sampled periodically (whenever one of the threads happens to be running at the time of the kernel's "hardclock" interrupt). The set of PC sample values obtained are saved in buffers which are sent to the specified <var>reply_port</var> in <strong>receive_samples</strong> messages. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_sample.html"><strong>thread_sample</strong></a>, <a href="receive_samples.html"><strong>receive_samples</strong></a>. \ No newline at end of file +<h2>task_sample</h2> +<hr> +<p> +<strong>Function</strong> - Sample the target task's thread program counters periodically. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_sample</strong> + <strong>(task_t</strong> <var>sample_task</var>, + <strong>mach_port_make_send_t</strong> <var>reply_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>sample_task</var> +<dd> +[in task send right] +Port for the task whose threads' PC are to be +sampled. +<p> +<dt> <var>reply_port</var> +<dd> +[in sample receive (to be converted to send) right] +Port to which PC sample buffers are sent. A value of <strong>MACH_PORT_NULL</strong> +stops PC sampling for the task. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_sample</strong> function causes the program counter (PC) of the +specified <var>sample_task</var> (actually, all of the threads within +<var>sample_task</var>) to be sampled periodically (whenever one of the threads +happens to be running at the time of the kernel's "hardclock" interrupt). +The set of PC sample values obtained are saved in buffers which are sent to +the specified <var>reply_port</var> in <strong>receive_samples</strong> messages. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_sample.html"><strong>thread_sample</strong></a>, +<a href="receive_samples.html"><strong>receive_samples</strong></a>. diff --git a/osfmk/man/task_set_emulation.html b/osfmk/man/task_set_emulation.html index a9b8e9fe6..1db18c5b5 100755 --- a/osfmk/man/task_set_emulation.html +++ b/osfmk/man/task_set_emulation.html @@ -1 +1,46 @@ -<h2>task_set_emulation</h2> <hr> <p> <strong>Function</strong> - Establish a user-level handler for a system call. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_set_emulation</strong> <strong>(task_t</strong> <var>task</var>, <strong>vm_address_t</strong> <var>routine_entry_pt</var>, <strong>int</strong> <var>syscall_number</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task port] The port for the task for which to establish the system call handler. <p> <dt> <var>routine_entry_pt</var> <dd> [in scalar] The address within the task of the handler for this particular system call. <p> <dt> <var>syscall_number</var> <dd> [in scalar] The number of the system call to be handled by this handler. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_set_emulation</strong> function establishes a handler within the task for a particular system call. When a thread executes a system call with this particular number, the system call will be redirected to the specified routine within the task's address space. This is expected to be an address within the transparent emulation library. These emulation handler addresses are inherited by child processes. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_set_emulation_vector.html"><strong>task_set_emulation_vector</strong></a>, <a href="task_get_emulation_vector.html"><strong>task_get_emulation_vector</strong></a>. \ No newline at end of file +<h2>task_set_emulation</h2> +<hr> +<p> +<strong>Function</strong> - Establish a user-level handler for a system call. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_set_emulation</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>vm_address_t</strong> <var>routine_entry_pt</var>, + <strong>int</strong> <var>syscall_number</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task port] The port for the task for which to establish the system call handler. +<p> +<dt> <var>routine_entry_pt</var> +<dd> +[in scalar] The address within the task of the handler for this particular system call. +<p> +<dt> <var>syscall_number</var> +<dd> +[in scalar] The number of the system call to be handled by this handler. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_set_emulation</strong> function establishes a handler within the task +for a particular system call. When a thread executes a system call +with this particular number, the system call will be redirected to the +specified routine within the task's address space. This is expected to +be an address within the transparent emulation library. These +emulation handler addresses are inherited by child processes. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual +address parameter. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_set_emulation_vector.html"><strong>task_set_emulation_vector</strong></a>, +<a href="task_get_emulation_vector.html"><strong>task_get_emulation_vector</strong></a>. diff --git a/osfmk/man/task_set_emulation_vector.html b/osfmk/man/task_set_emulation_vector.html index f496042d7..8296016d6 100755 --- a/osfmk/man/task_set_emulation_vector.html +++ b/osfmk/man/task_set_emulation_vector.html @@ -1 +1,61 @@ -<h2>task_set_emulation_vector</h2> <hr> <p> <strong>Function</strong> - Establish the target task's user-level system call handlers. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_set_emulation_vector</strong> <strong>(task_t</strong> <var>task</var>, <strong>int</strong> <var>vector_start</var>, <strong>emulation_vector_t</strong> <var>emulation_vector</var>, <strong>mach_msg_type_number_t</strong> <var>emulation_vector_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The port for the task for which to establish the system call handler. <p> <dt> <var>vector_start</var> <dd> [in scalar] The syscall number corresponding to the first element of <var>emulation_vector</var>. <p> <dt> <var>emulation_vector</var> <dd> [pointer to in array of <strong>vm_address_t</strong>] An array of routine entrypoints for the system calls starting with syscall number <var>vector_start</var>. <p> <dt> <var>emulation_vector_count</var> <dd> [in scalar] The number of elements in <var>emulation_vector</var>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_set_emulation_vector</strong> function establishes a handler within the task for a set of system calls. When a thread executes a system call with one of these numbers, the system call will be redirected to the corresponding routine within the task's address space. <p> These emulation handler addresses are inherited by child processes. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual addresses in the <var>emulation_vector</var> parameter. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_get_emulation_vector.html"><strong>task_get_emulation_vector</strong></a>. \ No newline at end of file +<h2>task_set_emulation_vector</h2> +<hr> +<p> +<strong>Function</strong> - Establish the target task's user-level system call handlers. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_set_emulation_vector</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>int</strong> <var>vector_start</var>, + <strong>emulation_vector_t</strong> <var>emulation_vector</var>, + <strong>mach_msg_type_number_t</strong> <var>emulation_vector_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task for which to establish the +system call handler. +<p> +<dt> <var>vector_start</var> +<dd> +[in scalar] +The syscall number corresponding to the first element of +<var>emulation_vector</var>. +<p> +<dt> <var>emulation_vector</var> +<dd> +[pointer to in array of <strong>vm_address_t</strong>] +An array of routine entrypoints +for the system calls starting with syscall number <var>vector_start</var>. +<p> +<dt> <var>emulation_vector_count</var> +<dd> +[in scalar] +The number of elements in <var>emulation_vector</var>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_set_emulation_vector</strong> function establishes +a handler within the task +for a set of system calls. When a thread executes a system call +with one of these +numbers, the system call will be redirected to the corresponding +routine within +the task's address space. +<p> +These emulation handler addresses are inherited by child processes. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the +virtual addresses +in the <var>emulation_vector</var> parameter. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_get_emulation_vector.html"><strong>task_get_emulation_vector</strong></a>. diff --git a/osfmk/man/task_set_exception_ports.html b/osfmk/man/task_set_exception_ports.html index a8f79fbd7..2ba56b674 100755 --- a/osfmk/man/task_set_exception_ports.html +++ b/osfmk/man/task_set_exception_ports.html @@ -1 +1,138 @@ -<h2>task_set_exception_ports</h2> <hr> <p> <strong>Function</strong> - Set target task's exception ports. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_set_exception_ports</strong> <strong>(task_t</strong> <var>task</var>, <strong>exception_mask_t</strong> <var>exception_types</var>, <strong>mach_port_t</strong> <var>exception_port</var>, <strong>exception_behavior_t</strong> <var>behavior</var>, <strong>thread_state_flavor_t</strong> <var>flavor</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task for which to set the ports. <p> <dt> <var>exception_types</var> <dd> [in scalar] A flag word indicating the types of exceptions for which the exception port applies: <dl> <p> <dt> <strong>EXC_MASK_BAD_ACCESS</strong> <dd> Could not access memory. <p> <dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> <dd> Instruction failed. Illegal or undefined instruction or operand. <p> <dt> <strong>EXC_MASK_ARITHMETIC</strong> <dd> Arithmetic exception <p> <dt> <strong>EXC_MASK_EMULATION</strong> <dd> Emulation instruction. Emulation support instruction encountered. <p> <dt> <strong>EXC_MASK_SOFTWARE</strong> <dd> Software generated exception. <p> <dt> <strong>EXC_MASK_BREAKPOINT</strong> <dd> Trace, breakpoint, etc. <p> <dt> <strong>EXC_MASK_SYSCALL</strong> <dd> System call requested. <p> <dt> <strong>EXC_MASK_MACH_SYSCALL</strong> <dd> System call with a number in the Mach call range requested. <p> <dt> <strong>EXC_MASK_RPC_ALERT </strong> <dd> Exceptional condition encountered during execution of RPC. </dl> <p> <dt> <var>exception_port</var> <dd> [in exception send right] The exception port for all selected exception types. <p> <dt> <var>behavior</var> <dd> [in scalar] The type of exception message to be sent. Defined types are: <dl> <p> <dt> <strong>EXCEPTION_DEFAULT</strong> <dd> Send a <strong>catch_exception_raise</strong> message including the thread identity. <p> <dt> <strong>EXCEPTION_STATE</strong> <dd> Send a <strong>catch_exception_raise_state</strong> message including the thread state. <p> <dt> <strong>EXCEPTION_STATE_PROTECTED</strong> <dd> Send a <strong>catch_exception_raise_state</strong> message including the thread state. Mark the exception port (and associated exceptions) as protected. <p> <dt> <strong>EXCEPTION_STATE_IDENTITY</strong> <dd> Send a <strong>catch_exception_raise_state_identity</strong> message including the thread identity and state. <p> <dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong> <dd> Send a <strong>catch_exception_raise_state_identity</strong> message including the thread identity and state. Mark the exception port (and associated exceptions) as protected. </dl> <p> <dt> <var>flavor</var> <dd> [in scalar] The type of state to be sent with the exception message. These types are defined in <strong><mach/thread_states.h></strong>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_set_exception_ports</strong> function sets a specified set of exception ports belonging to <var>task</var>. A task exception port is used when a thread specific exception port returns a non-success reply. <h3>NOTES</h3> <p> If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is the host name port, Mach kernel traps are executed by the kernel as expected; any other value causes the attempted execution of these system call numbers to be considered an exception. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_task_self.html"><strong>mach_task_self</strong></a>, <a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, <a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, <a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, <a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>, <a href="thread_abort.html"><strong>thread_abort</strong></a>. \ No newline at end of file +<h2>task_set_exception_ports</h2> +<hr> +<p> +<strong>Function</strong> - Set target task's exception ports. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_set_exception_ports</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>exception_mask_t</strong> <var>exception_types</var>, + <strong>mach_port_t</strong> <var>exception_port</var>, + <strong>exception_behavior_t</strong> <var>behavior</var>, + <strong>thread_state_flavor_t</strong> <var>flavor</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task for which to set the ports. +<p> +<dt> <var>exception_types</var> +<dd> +[in scalar] +A flag word indicating the types of exceptions for which the +exception port applies: +<dl> +<p> +<dt> <strong>EXC_MASK_BAD_ACCESS</strong> +<dd> +Could not access memory. +<p> +<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> +<dd> +Instruction failed. Illegal or undefined instruction or operand. +<p> +<dt> <strong>EXC_MASK_ARITHMETIC</strong> +<dd> +Arithmetic exception +<p> +<dt> <strong>EXC_MASK_EMULATION</strong> +<dd> +Emulation instruction. Emulation support instruction +encountered. +<p> +<dt> <strong>EXC_MASK_SOFTWARE</strong> +<dd> +Software generated exception. +<p> +<dt> <strong>EXC_MASK_BREAKPOINT</strong> +<dd> +Trace, breakpoint, etc. +<p> +<dt> <strong>EXC_MASK_SYSCALL</strong> +<dd> +System call requested. +<p> +<dt> <strong>EXC_MASK_MACH_SYSCALL</strong> +<dd> +System call with a number in the Mach call range requested. +<p> +<dt> <strong>EXC_MASK_RPC_ALERT </strong> +<dd> +Exceptional condition encountered during execution of RPC. +</dl> +<p> +<dt> <var>exception_port</var> +<dd> +[in exception send right] +The exception port for all selected exception +types. +<p> +<dt> <var>behavior</var> +<dd> +[in scalar] +The type of exception message to be sent. Defined types are: +<dl> +<p> +<dt> <strong>EXCEPTION_DEFAULT</strong> +<dd> +Send a <strong>catch_exception_raise</strong> message including the thread +identity. +<p> +<dt> <strong>EXCEPTION_STATE</strong> +<dd> +Send a <strong>catch_exception_raise_state</strong> message including the +thread state. +<p> +<dt> <strong>EXCEPTION_STATE_PROTECTED</strong> +<dd> +Send a <strong>catch_exception_raise_state</strong> message including the +thread state. Mark the exception port (and associated +exceptions) as protected. +<p> +<dt> <strong>EXCEPTION_STATE_IDENTITY</strong> +<dd> +Send a <strong>catch_exception_raise_state_identity</strong> message +including the thread identity and state. +<p> +<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong> +<dd> +Send a <strong>catch_exception_raise_state_identity</strong> message +including the thread identity and state. Mark the exception port +(and associated exceptions) as protected. +</dl> +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of state to be sent with the exception message. +These types are defined in <strong><mach/thread_states.h></strong>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_set_exception_ports</strong> function sets a specified +set of exception ports belonging to <var>task</var>. A task exception port +is used when a thread specific exception port returns a non-success reply. +<h3>NOTES</h3> +<p> +If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is +the host name port, Mach kernel traps are executed by the kernel as expected; +any other value causes the attempted execution of these system call numbers to +be considered an exception. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_task_self.html"><strong>mach_task_self</strong></a>, +<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, +<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, +<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, +<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, +<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>, +<a href="thread_abort.html"><strong>thread_abort</strong></a>. diff --git a/osfmk/man/task_set_info.html b/osfmk/man/task_set_info.html index 935cc2c66..3a8e3a466 100755 --- a/osfmk/man/task_set_info.html +++ b/osfmk/man/task_set_info.html @@ -1 +1,44 @@ -<H2>task_set_info</h2> <hr> <p> <strong>Function</strong> - Set task-specific information state. <h3>SYNOPSIS</h3> <pre> <strong>#include<task_info.h></strong> <strong>kern_return_t task_set_info</strong> <strong>(task_t</strong> <var>target_task</var>, <strong>task_flavor_t</strong> <var>flavor</var>, <strong>task_info_t</strong> <var>task_info</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> The task whose information is to be set. <p> <dt> <var>flavor</var> <dd> Specifies the type of information to be set. Currently the interface supports the setting of a single flavor: <strong>TASK_USER_DATA</strong>. <p> <dt> <var>task_info</var> <dd> Specifies the information to be set. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_set_info</strong> interface provides the caller with the means to set the target task's <var>user_data</var> field. This field may be used to specify arbitrarily task-specific data. <h3>NOTES</h3> <p> Currently, this interface is used exclusively to provide freshly colocated user tasks with the short-circuited RPC glue vector. <h3>RETURN VALUES</h3> <p> Only generic values apply. <h3>RELATED INFORMATION</h3> <p> \ No newline at end of file +<H2>task_set_info</h2> +<hr> +<p> +<strong>Function</strong> - Set task-specific information state. +<h3>SYNOPSIS</h3> +<pre> +<strong>#include<task_info.h></strong> + +<strong>kern_return_t task_set_info</strong> + <strong>(task_t</strong> <var>target_task</var>, + <strong>task_flavor_t</strong> <var>flavor</var>, + <strong>task_info_t</strong> <var>task_info</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +The task whose information is to be set. +<p> +<dt> <var>flavor</var> +<dd> +Specifies the type of information to be set. Currently the interface +supports the setting of a single flavor: +<strong>TASK_USER_DATA</strong>. +<p> +<dt> <var>task_info</var> +<dd> +Specifies the information to be set. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_set_info</strong> interface provides the caller with +the means to set the target task's <var>user_data</var> field. This +field may be used to specify arbitrarily task-specific data. +<h3>NOTES</h3> +<p> +Currently, this interface is used exclusively to provide freshly +colocated user tasks with the short-circuited RPC glue vector. +<h3>RETURN VALUES</h3> +<p> +Only generic values apply. +<h3>RELATED INFORMATION</h3> +<p> diff --git a/osfmk/man/task_set_policy.html b/osfmk/man/task_set_policy.html index 8b4607689..35c063cf7 100755 --- a/osfmk/man/task_set_policy.html +++ b/osfmk/man/task_set_policy.html @@ -1 +1,80 @@ -<h2>task_set_policy</h2> <hr> <p> <strong>Function</strong> - Set target task's default scheduling policy state. (Protected Interface.) <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_set_policy</strong> <strong>(task_t</strong> <var>task</var>, <strong>processor_set_t</strong> <var>processor_set</var>, <strong>policy_t</strong> <var>policy</var>, <strong>policy_base_t</strong> <var>base</var>, <strong>mach_msg_type_number_t</strong> <var>base_count</var>, <strong>policy_limit_t</strong> <var>limit</var>, <strong>mach_msg_type_number_t</strong> <var>limit_count</var>, <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>task</var> <dd> [in task send right] The task whose scheduling policy is to be set. <dt> <var>processor_set</var> <dd> [in processor-set-control send right] The control port for the processor set to which the task is currently assigned. <dt> <var>policy</var> <dd> [in scalar] Policy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>, <strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out). <dt> <var>base</var> <dd> [pointer to in structure] Base policy specific data, <strong>policy_fifo_base</strong>, <strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>. <dt> <var>base_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). <dt> <var>limit</var> <dd> [pointer to in structure] Policy specific limits, <strong>policy_fifo_limit</strong>, <strong>policy_rr_limit</strong> or <strong>policy_timeshare_limit</strong>. <dt> <var>limit_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). <dt> <var>change_threads</var> <dd> [in scalar] True if the scheduling attributes for all contained threads should be changed as well. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_set_policy</strong> function sets the scheduling attributes, both base and limit, for <var>task</var>. <var>policy</var> may be any policy implemented by the processor set whether or not it is enabled. <h3>RETURN VALUES</h3> <dl> <dt> <strong>KERN_INVALID_PROCESSOR_SET</strong> <dd> <var>processor_set</var> is not the task's processor set control port. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, <a href="thread_policy.html"><strong>thread_policy</strong></a>, <a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>, <a href="task_policy.html"><strong>task_policy</strong></a>. <p> Data Structures: <a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, <a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, <a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. \ No newline at end of file +<h2>task_set_policy</h2> +<hr> +<p> +<strong>Function</strong> - Set target task's default scheduling policy state. (Protected Interface.) +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_set_policy</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>processor_set_t</strong> <var>processor_set</var>, + <strong>policy_t</strong> <var>policy</var>, + <strong>policy_base_t</strong> <var>base</var>, + <strong>mach_msg_type_number_t</strong> <var>base_count</var>, + <strong>policy_limit_t</strong> <var>limit</var>, + <strong>mach_msg_type_number_t</strong> <var>limit_count</var>, + <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>task</var> +<dd> +[in task send right] +The task whose scheduling policy is to be set. +<dt> <var>processor_set</var> +<dd> +[in processor-set-control send right] +The control port for the processor +set to which the task is currently assigned. +<dt> <var>policy</var> +<dd> +[in scalar] +Policy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>, +<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out). +<dt> <var>base</var> +<dd> +[pointer to in structure] +Base policy specific data, <strong>policy_fifo_base</strong>, +<strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>. +<dt> <var>base_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +<dt> <var>limit</var> +<dd> +[pointer to in structure] +Policy specific limits, <strong>policy_fifo_limit</strong>, +<strong>policy_rr_limit</strong> or <strong>policy_timeshare_limit</strong>. +<dt> <var>limit_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +<dt> <var>change_threads</var> +<dd> +[in scalar] +True if the scheduling attributes for all contained threads +should be changed as well. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_set_policy</strong> function sets the scheduling attributes, +both base and limit, for <var>task</var>. +<var>policy</var> may be any policy implemented by the processor set whether or +not it is enabled. +<h3>RETURN VALUES</h3> +<dl> +<dt> <strong>KERN_INVALID_PROCESSOR_SET</strong> +<dd> +<var>processor_set</var> is not the task's processor set control port. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, +<a href="thread_policy.html"><strong>thread_policy</strong></a>, +<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>, +<a href="task_policy.html"><strong>task_policy</strong></a>. +<p> +Data Structures: +<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, +<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, +<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. diff --git a/osfmk/man/task_set_port_space.html b/osfmk/man/task_set_port_space.html index b1408ccfe..4dddda273 100755 --- a/osfmk/man/task_set_port_space.html +++ b/osfmk/man/task_set_port_space.html @@ -1 +1,37 @@ -<h2>task_set_port_space</h2> <hr> <p> <strong>Function</strong> - Set the size of the target task's port name space table. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_set_port_space</strong> <strong>(task_t</strong> <var>task</var>, <strong>int</strong> <var>table_entries</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in send right] The port referencing the task whose port name space is to be set. <p> <dt> <var>table_entries</var> <dd> [in scalar] The number of entries in the port name space table. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_set_port_space</strong> function preallocates the specified number of entries in the specified task's IPC name space. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_NO_SPACE</strong> <dd> The requested table size exceeds the maximum allowable table size. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>. \ No newline at end of file +<h2>task_set_port_space</h2> +<hr> +<p> +<strong>Function</strong> - Set the size of the target task's port name space table. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_set_port_space</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>int</strong> <var>table_entries</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in send right] The port referencing the task whose port name space is +to be set. +<p> +<dt> <var>table_entries</var> +<dd> +[in scalar] The number of entries in the port name space table. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_set_port_space</strong> function preallocates the specified number of +entries in the specified task's IPC name space. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_NO_SPACE</strong> +<dd> +The requested table size exceeds the maximum allowable table size. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>. diff --git a/osfmk/man/task_set_special_port.html b/osfmk/man/task_set_special_port.html index 7fe7bf6a7..55cc0d716 100755 --- a/osfmk/man/task_set_special_port.html +++ b/osfmk/man/task_set_special_port.html @@ -1 +1,110 @@ -<h2>task_set_special_port</h2> <hr> <p> <strong>Function</strong> - Set the indicated special port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_set_special_port</strong> <strong>(task_t</strong> <var>task</var>, <strong>int</strong> <var>which_port</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> <strong>Macro forms:</strong> <strong>kern_return_t task_set_bootstrap_port</strong> <strong>(task_t</strong> <var>task</var>, <strong>int</strong> <var>which_port</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> <strong>kern_return_t task_set_kernel_port</strong> <strong>(task_t</strong> <var>task</var>, <strong>int</strong> <var>which_port</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> <strong>kern_return_t task_set_host_name_port</strong> <strong>(task_t</strong> <var>task</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The port for the task for which to set the port. <p> <dt> <var>which_port</var> <dd> [in scalar] The special port to be set. Valid values are: <dl> <p> <dt> <strong>TASK_BOOTSTRAP_PORT</strong> <dd> [bootstrap send right] The task's bootstrap port. Used to send messages requesting return of other system service ports. <p> <dt> <strong>TASK_KERNEL_PORT</strong> <dd> [task-self send right] The task's kernel port. Used by the kernel to receive messages to manipulate the task. This is the port returned by <strong>mach_task_self</strong>. Setting this special port does not change the identity of the kernel port that names the task; this simply changes the value returned as the kernel special port. <p> <dt> <strong>TASK_HOST_NAME_PORT</strong> <dd> [host-self send right] The task's host self port. Used by the task to request information about its containing host. This is the port returned by <strong>mach_host_self</strong>. Setting this special port does not change the identity of the kernel port that names the host; this simply changes the value returned as the host special port. <p> <dt> <strong>TASK_WIRED_LEDGER_PORT</strong> <dd> [ledger send right] The resource ledger from which the task draws its wired kernel memory. Setting this special port does not change the ledger from which the task draws its resources; this simply changes the value returned as the ledger special port. <p> <dt> <strong>TASK_PAGED_LEDGER_PORT</strong> <dd> [ledger send right] The resource ledger from which the task draws its default memory managed memory. Setting this special port does not change the ledger from which the task draws its resources; this simply changes the value returned as the ledger special port. </dl> <p> <dt> <var>special_port</var> <dd> [in task-special send right] The value for the port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_set_special_port</strong> function sets a special port belonging to <var>task</var>. <h3>NOTES</h3> <p> The current implementation does not support the <strong>TASK_HOST_NAME_PORT</strong> features associated with this interface. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>, <a href="mach_task_self.html"><strong>mach_task_self</strong></a>, <a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>, <a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>, <a href="mach_host_self.html"><strong>mach_host_self</strong></a>. \ No newline at end of file +<h2>task_set_special_port</h2> +<hr> +<p> +<strong>Function</strong> - Set the indicated special port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_set_special_port</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>int</strong> <var>which_port</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + + +<strong>Macro forms:</strong> + + +<strong>kern_return_t task_set_bootstrap_port</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>int</strong> <var>which_port</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + + +<strong>kern_return_t task_set_kernel_port</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>int</strong> <var>which_port</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> + + +<strong>kern_return_t task_set_host_name_port</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task for which to set the port. +<p> +<dt> <var>which_port</var> +<dd> +[in scalar] +The special port to be set. Valid values are: +<dl> +<p> +<dt> <strong>TASK_BOOTSTRAP_PORT</strong> +<dd> +[bootstrap send right] The task's bootstrap port. Used to send +messages requesting return of other system service ports. +<p> +<dt> <strong>TASK_KERNEL_PORT</strong> +<dd> +[task-self send right] The task's kernel port. Used by the +kernel to receive messages to manipulate the task. This is the +port returned by <strong>mach_task_self</strong>. Setting this special port +does not change the identity of the kernel port that names the +task; this simply changes the value returned as the kernel +special port. +<p> +<dt> <strong>TASK_HOST_NAME_PORT</strong> +<dd> +[host-self send right] The task's host self port. Used by the +task to request information about its containing host. This is +the port returned by <strong>mach_host_self</strong>. Setting this special port +does not change the identity of the kernel port that names the +host; this simply changes the value returned as the host +special port. +<p> +<dt> <strong>TASK_WIRED_LEDGER_PORT</strong> +<dd> +[ledger send right] The resource ledger from which the task +draws its wired kernel memory. Setting this special port does +not change the ledger from which the task draws its resources; +this simply changes the value returned as the ledger special +port. +<p> +<dt> <strong>TASK_PAGED_LEDGER_PORT</strong> +<dd> +[ledger send right] The resource ledger from which the task +draws its default memory managed memory. Setting this +special port does not change the ledger from which the task +draws its resources; this simply changes the value returned as +the ledger special port. +</dl> +<p> +<dt> <var>special_port</var> +<dd> +[in task-special send right] +The value for the port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_set_special_port</strong> function sets a special port +belonging to <var>task</var>. +<h3>NOTES</h3> +<p> +The current implementation does not support the <strong>TASK_HOST_NAME_PORT</strong> +features associated with this interface. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>, +<a href="mach_task_self.html"><strong>mach_task_self</strong></a>, +<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>, +<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>, +<a href="mach_host_self.html"><strong>mach_host_self</strong></a>. diff --git a/osfmk/man/task_suspend.html b/osfmk/man/task_suspend.html index 9e6979b98..3b8badbd9 100755 --- a/osfmk/man/task_suspend.html +++ b/osfmk/man/task_suspend.html @@ -1 +1,41 @@ -<h2>task_suspend</h2> <hr> <p> <strong>Function</strong> - Suspend the target task. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_suspend</strong> <strong>(task_t</strong> <var>task</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The port for the task to be suspended. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_suspend</strong> function increments the suspend count for task and stops all threads within the task. As long as the suspend count is positive, no newly-created threads can execute. The function does not return until all of the task's threads have been suspended. <h3>NOTES</h3> <p> To resume a suspended task and its threads, use <strong>task_resume</strong>. If the suspend count is greater than one, <strong>task_resume</strong> must be repeated that number of times. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="task_info.html"><strong>task_info</strong></a>, <a href="task_resume.html"><strong>task_resume</strong></a>, <a href="task_terminate.html"><strong>task_terminate</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>. \ No newline at end of file +<h2>task_suspend</h2> +<hr> +<p> +<strong>Function</strong> - Suspend the target task. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_suspend</strong> + <strong>(task_t</strong> <var>task</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task to be suspended. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_suspend</strong> function increments the suspend count +for task and stops all +threads within the task. As long as the suspend count is positive, +no newly-created threads can execute. The function does not return until all +of the task's threads have been suspended. +<h3>NOTES</h3> +<p> +To resume a suspended task and its threads, use <strong>task_resume</strong>. +If the suspend +count is greater than one, <strong>task_resume</strong> must be repeated +that number of times. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="task_resume.html"><strong>task_resume</strong></a>, +<a href="task_terminate.html"><strong>task_terminate</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>. diff --git a/osfmk/man/task_swap_exception_ports.html b/osfmk/man/task_swap_exception_ports.html index 481cd7790..cfcb41986 100755 --- a/osfmk/man/task_swap_exception_ports.html +++ b/osfmk/man/task_swap_exception_ports.html @@ -1 +1,176 @@ -<h2>task_swap_exception_ports</h2> <hr> <p> <strong>Function</strong> - Set target task's exception ports, returning the previous exception ports. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_swap_exception_ports</strong> <strong>(task_t</strong> <var>task</var>, <strong>exception_mask_t</strong> <var>exception_types</var>, <strong>mach_port_t</strong> <var>exception_port</var>, <strong>exception_behavior_t</strong> <var>behavior</var>, <strong>thread_state_flavor_t</strong> <var>flavor</var>, <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>, <strong>old_exception_masks</strong> <var>old_exception_count</var>, <strong>exception_port_array_t</strong> <var>old_exception_ports</var>, <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>, <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The task for which to set the ports. <p> <dt> <var>exception_types</var> <dd> [in scalar] A flag word indicating the types of exceptions for which the exception port applies: <dl> <p> <dt> <strong>EXC_MASK_BAD_ACCESS</strong> <dd> Could not access memory. <p> <dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> <dd> Instruction failed. Illegal or undefined instruction or operand. <p> <dt> <strong>EXC_MASK_ARITHMETIC</strong> <dd> Arithmetic exception <p> <dt> <strong>EXC_MASK_EMULATION</strong> <dd> Emulation instruction. Emulation support instruction encountered. <p> <dt> <strong>EXC_MASK_SOFTWARE</strong> <dd> Software generated exception. <p> <dt> <strong>EXC_MASK_BREAKPOINT</strong> <dd> Trace, breakpoint, etc. <p> <dt> <strong>EXC_MASK_SYSCALL</strong> <dd> System call requested. <p> <dt> <strong>EXC_MASK_MACH_SYSCALL</strong> <dd> System call with a number in the Mach call range requested. <p> <dt> <strong>EXC_MASK_RPC_ALERT </strong> <dd> Exceptional condition encountered during execution of RPC. </dl> <p> <dt> <var>exception_port</var> <dd> [in exception send right] The exception port for all selected exception types. <p> <dt> <var>behavior</var> <dd> [in scalar] The type of exception message to be sent. Defined types are: <dl> <p> <dt> <strong>EXCEPTION_DEFAULT</strong> <dd> Send a <strong>catch_exception_raise</strong> message including the thread identity. <p> <dt> <strong>EXCEPTION_STATE</strong> <dd> Send a <strong>catch_exception_raise_state</strong> message including the thread state. <p> <dt> <strong>EXCEPTION_STATE_PROTECTED</strong> <dd> Send a <strong>catch_exception_raise_state</strong> message including the thread state. Mark the exception port (and associated exceptions) as protected. <p> <dt> <strong>EXCEPTION_STATE_IDENTITY</strong> <dd> Send a <strong>catch_exception_raise_state_identity</strong> message including the thread identity and state. <p> <dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong> <dd> Send a <strong>catch_exception_raise_state_identity</strong> message including the thread identity and state. Mark the exception port (and associated exceptions) as protected. </dl> <p> <dt> <var>flavor</var> <dd> [in scalar] The type of state to be sent with the exception message. These types are defined in <strong><mach/thread_states.h></strong>. <p> <dt> <var>old_exception_masks</var> <dd> [out array of <var>exception_mask_t</var>] An array, each element being a mask specifying for which exception types the corresponding element of the other arrays apply. <p> <dt> <var>old_exception_count</var> <dd> [pointer to in/out scalar] On input, the maximum size of the array buffers; on output, the number of returned <exception type mask, exception port, behavior, flavor> sets returned. <p> <dt> <var>old_exception_ports</var> <dd> [out array of exception send rights] The returned exception ports. <p> <dt> <var>old_behaviors</var> <dd> [out array of <var>exception_behavior_t</var>] The type of exception message to be sent as with <var>behavior</var>. <p> <dt> <var>old_flavors</var> <dd> [out array of <var>thread_state_flavor_t</var>] The type of state to be sent with the exception message. These types are defined in <strong><mach/thread_states.h></strong>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_swap_exception_ports</strong> function sets a specified set of exception ports belonging to <var>task</var>, returning the old set. A task exception port is used when a thread specific exception port returns a non-success reply. <h3>NOTES</h3> <p> If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is the host name port, Mach kernel traps are executed by the kernel as expected; any other value causes the attempted execution of these system call numbers to be considered an exception. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_task_self.html"><strong>mach_task_self</strong></a>, <a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, <a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, <a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>, <a href="thread_abort.html"><strong>thread_abort</strong></a>. \ No newline at end of file +<h2>task_swap_exception_ports</h2> +<hr> +<p> +<strong>Function</strong> - Set target task's exception ports, returning the previous exception ports. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_swap_exception_ports</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>exception_mask_t</strong> <var>exception_types</var>, + <strong>mach_port_t</strong> <var>exception_port</var>, + <strong>exception_behavior_t</strong> <var>behavior</var>, + <strong>thread_state_flavor_t</strong> <var>flavor</var>, + <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>, + <strong>old_exception_masks</strong> <var>old_exception_count</var>, + <strong>exception_port_array_t</strong> <var>old_exception_ports</var>, + <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>, + <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The task for which to set the ports. +<p> +<dt> <var>exception_types</var> +<dd> +[in scalar] +A flag word indicating the types of exceptions for which the +exception port applies: +<dl> +<p> +<dt> <strong>EXC_MASK_BAD_ACCESS</strong> +<dd> +Could not access memory. +<p> +<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> +<dd> +Instruction failed. Illegal or undefined instruction or operand. +<p> +<dt> <strong>EXC_MASK_ARITHMETIC</strong> +<dd> +Arithmetic exception +<p> +<dt> <strong>EXC_MASK_EMULATION</strong> +<dd> +Emulation instruction. Emulation support instruction +encountered. +<p> +<dt> <strong>EXC_MASK_SOFTWARE</strong> +<dd> +Software generated exception. +<p> +<dt> <strong>EXC_MASK_BREAKPOINT</strong> +<dd> +Trace, breakpoint, etc. +<p> +<dt> <strong>EXC_MASK_SYSCALL</strong> +<dd> +System call requested. +<p> +<dt> <strong>EXC_MASK_MACH_SYSCALL</strong> +<dd> +System call with a number in the Mach call range requested. +<p> +<dt> <strong>EXC_MASK_RPC_ALERT </strong> +<dd> +Exceptional condition encountered during execution of RPC. +</dl> +<p> +<dt> <var>exception_port</var> +<dd> +[in exception send right] +The exception port for all selected exception +types. +<p> +<dt> <var>behavior</var> +<dd> +[in scalar] +The type of exception message to be sent. Defined types are: +<dl> +<p> +<dt> <strong>EXCEPTION_DEFAULT</strong> +<dd> +Send a <strong>catch_exception_raise</strong> message including the thread +identity. +<p> +<dt> <strong>EXCEPTION_STATE</strong> +<dd> +Send a <strong>catch_exception_raise_state</strong> message including the +thread state. +<p> +<dt> <strong>EXCEPTION_STATE_PROTECTED</strong> +<dd> +Send a <strong>catch_exception_raise_state</strong> message including the +thread state. Mark the exception port (and associated +exceptions) as protected. +<p> +<dt> <strong>EXCEPTION_STATE_IDENTITY</strong> +<dd> +Send a <strong>catch_exception_raise_state_identity</strong> message +including the thread identity and state. +<p> +<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong> +<dd> +Send a <strong>catch_exception_raise_state_identity</strong> message +including the thread identity and state. Mark the exception port +(and associated exceptions) as protected. +</dl> +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of state to be sent with the exception message. +These types are defined in <strong><mach/thread_states.h></strong>. +<p> +<dt> <var>old_exception_masks</var> +<dd> +[out array of <var>exception_mask_t</var>] +An array, each element being a mask +specifying for which exception types the corresponding element of the +other arrays apply. +<p> +<dt> <var>old_exception_count</var> +<dd> +[pointer to in/out scalar] +On input, the maximum size of the array +buffers; on output, the number of returned <exception type mask, +exception port, behavior, flavor> sets returned. +<p> +<dt> <var>old_exception_ports</var> +<dd> +[out array of exception send rights] +The returned exception ports. +<p> +<dt> <var>old_behaviors</var> +<dd> +[out array of <var>exception_behavior_t</var>] +The type of exception message to +be sent as with <var>behavior</var>. +<p> +<dt> <var>old_flavors</var> +<dd> +[out array of <var>thread_state_flavor_t</var>] +The type of state to be sent with +the exception message. These types are defined in <strong><mach/thread_states.h></strong>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_swap_exception_ports</strong> function sets a specified +set of exception +ports belonging to <var>task</var>, returning the old set. A task exception +port is used when +a thread specific exception port returns a non-success reply. +<h3>NOTES</h3> +<p> +If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is +the host name port, Mach kernel traps are executed by the kernel as expected; +any other value causes the attempted execution of these system call numbers to +be considered an exception. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_task_self.html"><strong>mach_task_self</strong></a>, +<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, +<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, +<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, +<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, +<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>, +<a href="thread_abort.html"><strong>thread_abort</strong></a>. diff --git a/osfmk/man/task_terminate.html b/osfmk/man/task_terminate.html index 6e340f57e..88ea50ad1 100755 --- a/osfmk/man/task_terminate.html +++ b/osfmk/man/task_terminate.html @@ -1 +1,35 @@ -<h2>task_terminate</h2> <hr> <p> <strong>Function</strong> - Terminate the target task and deallocate its resources. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_terminate</strong> <strong>(task_t</strong> <var>task</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The port for the task to be destroyed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_terminate</strong> function kills task and all its threads, if any. The kernel frees all resources that are in use by the task. The kernel destroys any port for which the task holds the receive right. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="task_suspend.html"><strong>task_suspend</strong></a>, <a href="task_resume.html"><strong>task_resume</strong></a>, <a href="thread_terminate.html"><strong>thread_terminate</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>. \ No newline at end of file +<h2>task_terminate</h2> +<hr> +<p> +<strong>Function</strong> - Terminate the target task and deallocate its resources. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_terminate</strong> + <strong>(task_t</strong> <var>task</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task to be destroyed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_terminate</strong> function kills task and all its +threads, if any. The kernel +frees all resources that are in use by the task. The kernel +destroys any port for +which the task holds the receive right. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="task_suspend.html"><strong>task_suspend</strong></a>, +<a href="task_resume.html"><strong>task_resume</strong></a>, +<a href="thread_terminate.html"><strong>thread_terminate</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>. diff --git a/osfmk/man/task_thread_times_info.html b/osfmk/man/task_thread_times_info.html index 50867b4ab..6b58716a7 100755 --- a/osfmk/man/task_thread_times_info.html +++ b/osfmk/man/task_thread_times_info.html @@ -1 +1,41 @@ -<h2>task_thread_times_info</h2> <hr> <p> <strong>Structure</strong> - Defines thread execution times information for tasks. <h3>SYNOPSIS</h3> <pre> <strong>struct task_thread_times_info</strong> <strong>{</strong> <strong>time_value_t</strong> <var>user_time</var><strong>;</strong> <strong>time_value_t</strong> <var>system_time</var><strong>;</strong> <strong>};</strong> <strong>typedef struct task_thread_times_info* task_thread_times_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <p> <dt> <var>user_time</var> <dd> Total user run time for live threads. <p> <dt> <var>system_time</var> <dd> Total system run time for live threads. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_thread_times_info</strong> structure defines thread execution time statistics for tasks. The <strong>task_info</strong> function returns these times for a specified task. The <strong>thread_info</strong> function returns this information for a specific thread. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_info.html"><strong>task_info</strong></a>, <a href="thread_info.html"><strong>thread_info</strong></a>. <p> Data Structures: <a href="task_basic_info.html"><strong>task_basic_info</strong></a>, <a href="thread_basic_info.html"><strong>thread_basic_info</strong></a>. \ No newline at end of file +<h2>task_thread_times_info</h2> +<hr> +<p> +<strong>Structure</strong> - Defines thread execution times information for tasks. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct task_thread_times_info</strong> +<strong>{</strong> + <strong>time_value_t</strong> <var>user_time</var><strong>;</strong> + <strong>time_value_t</strong> <var>system_time</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct task_thread_times_info* task_thread_times_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> + <p> +<dt> <var>user_time</var> +<dd> +Total user run time for live threads. + <p> +<dt> <var>system_time</var> +<dd> +Total system run time for live threads. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_thread_times_info</strong> structure defines thread +execution time statistics +for tasks. The <strong>task_info</strong> function returns these times +for a specified task. The +<strong>thread_info</strong> function returns this information for a specific thread. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="thread_info.html"><strong>thread_info</strong></a>. +<p> +Data Structures: +<a href="task_basic_info.html"><strong>task_basic_info</strong></a>, +<a href="thread_basic_info.html"><strong>thread_basic_info</strong></a>. diff --git a/osfmk/man/task_threads.html b/osfmk/man/task_threads.html index 7321c1a30..4dec84bd2 100755 --- a/osfmk/man/task_threads.html +++ b/osfmk/man/task_threads.html @@ -1 +1,46 @@ -<h2>task_threads</h2> <hr> <p> <strong>Function</strong> - Return the target task's list of threads. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t task_threads</strong> <strong>(task_t</strong> <var>task</var>, <strong>thread_act_port_array_t</strong> <var>thread_list</var>, <strong>mach_msg_type_number_t*</strong> <var>thread_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The port for the task for which the thread list is to be returned. <p> <dt> <var>thread_list</var> <dd> [out pointer to dynamic array of thread send rights] The returned list of threads within <var>task</var>, in no particular order. <p> <dt> <var>thread_count</var> <dd> [out scalar] The returned count of threads in <var>thread_list</var>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>task_threads</strong> function returns a list of the threads within <var>task</var>. The calling task or thread also receives a send right to the kernel port for each listed thread. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_terminate.html"><strong>thread_terminate</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>. \ No newline at end of file +<h2>task_threads</h2> +<hr> +<p> +<strong>Function</strong> - Return the target task's list of threads. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t task_threads</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>thread_act_port_array_t</strong> <var>thread_list</var>, + <strong>mach_msg_type_number_t*</strong> <var>thread_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] +The port for the task for which the thread list is to +be returned. +<p> +<dt> <var>thread_list</var> +<dd> +[out pointer to dynamic array of thread send rights] +The returned list of +threads within <var>task</var>, in no particular order. +<p> +<dt> <var>thread_count</var> +<dd> +[out scalar] +The returned count of threads in <var>thread_list</var>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>task_threads</strong> function returns a list of the threads +within <var>task</var>. The calling +task or thread also receives a send right to the kernel port +for each listed thread. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_terminate.html"><strong>thread_terminate</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>. diff --git a/osfmk/man/thread_abort.html b/osfmk/man/thread_abort.html index 3f541fb58..3130a22c7 100755 --- a/osfmk/man/thread_abort.html +++ b/osfmk/man/thread_abort.html @@ -1 +1,127 @@ -<h2>thread_abort</h2> <hr> <p> <strong>Function</strong> - Abort a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_abort</strong> <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_thread</var> <dd> [in thread send right] The thread to be aborted. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_abort</strong> function aborts page faults and any message primitive calls in use by <var>target_thread</var>. Scheduling depressions and clock sleeps are also aborted. The call returns a code indicating that it was interrupted. The call is interrupted even if the thread (or the task containing it) is suspended. If it is suspended, the thread receives the interrupt when it resumes. <p> If its state is not modified before it resumes, the thread will retry an aborted page fault. The Mach message trap returns either <strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending on whether the send or the receive side was interrupted. Note, though, that the Mach message trap is contained within the <strong>mach_msg</strong> library routine, which, by default, retries interrupted message calls. <p> The basic purpose of <strong>thread_abort</strong> is to let one thread cleanly stop another thread (<var>target_thread</var>). The target thread is stopped in such a manner that its future execution can be controlled in a predictable way. When <strong>thread_abort</strong> returns, the target thread will appear to have just returned from the kernel (if it had been in kernel mode). <h3>NOTES</h3> <p> By way of comparison, the <strong>thread_suspend</strong> function keeps the target thread from executing any further instructions at the user level, including the return from a system call. The <strong>thread_get_state</strong> function returns the thread's user state, while <strong>thread_set_state</strong> allows modification of the user state. <p> A problem occurs if a suspended thread had been executing within a system call. In this case, the thread has, not only a user state, but an associated kernel state. (The kernel state cannot be changed with <strong>thread_set_state</strong>.) As a result, when the thread resumes, the system call can return, producing a change in the user state and, possibly, user memory. <p> For a thread executing within a system call, <strong>thread_abort</strong> aborts the kernel call from the thread's point of view. Specifically, it resets the kernel state so that the thread will resume execution at the system call return, with the return code value set to one of the interrupted codes. The system call itself may be completed entirely, aborted entirely or be partially completed, depending on when the abort is received. As a result, if the thread's user state has been modified by <strong>thread_set_state</strong>, it will not be altered un-predictably by any unexpected system call side effects. <p> For example, to simulate a POSIX signal, use the following sequence of calls: <dl> <dd> <strong>thread_suspend</strong>\(emTo stop the thread. <dd> <strong>thread_abort</strong>\(emTo interrupt any system call in progress and set the return value to "interrupted". Because the thread is already stopped, it will not return to user code. <dd> <strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a procedure call to the signal handler. <dd> <strong>thread_resume</strong>\(emTo resume execution at the signal handler. If the thread's stack is set up correctly, the thread can return to the interrupted system call. Note that the code to push an extra stack frame and change the registers is highly machine dependent. </dl> <h3>CAUTIONS</h3> <p> As a rule, do not use <strong>thread_abort</strong> on a non-suspended thread. This operation is very risky because it is difficult to know which system trap, if any, is executing and whether an interrupt return will result in some useful action by the thread. <p> <strong>thread_abort</strong> will abort any non-atomic operation (such as a multi-page <strong>memory_object_data_supply</strong>) at an arbitrary point in a non-restartable way. Such problems can be avoided by using <strong>thread_abort_safely</strong>. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_EXCEPTION_PROTECTED</strong> <dd> The thread is processing a protected exception. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="thread_get_state.html"><strong>thread_get_state</strong></a>, <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="thread_set_state.html"><strong>thread_set_state</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>, <a href="thread_terminate.html"><strong>thread_terminate</strong></a>, <a href="thread_abort_safely.html"><strong>thread_abort_safely</strong></a>, <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>. \ No newline at end of file +<h2>thread_abort</h2> +<hr> +<p> +<strong>Function</strong> - Abort a thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_abort</strong> + <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_thread</var> +<dd> +[in thread send right] +The thread to be aborted. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_abort</strong> function aborts page faults and any +message primitive calls +in use by <var>target_thread</var>. Scheduling depressions and clock sleeps are also +aborted. The call returns a code indicating that it was interrupted. +The call is +interrupted even if the thread (or the task containing it) is +suspended. If it is +suspended, the thread receives the interrupt when it resumes. +<p> +If its state is not modified before it resumes, the thread will +retry an aborted +page fault. The Mach message trap returns either +<strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending +on whether the send or the +receive side was interrupted. Note, though, that the Mach message trap is +contained within the <strong>mach_msg</strong> library routine, which, +by default, retries +interrupted message calls. +<p> +The basic purpose of <strong>thread_abort</strong> is to let one thread +cleanly stop another thread (<var>target_thread</var>). +The target thread is stopped in such a manner that its +future execution can be controlled in a predictable way. When +<strong>thread_abort</strong> +returns, the target thread will appear to have just returned +from the kernel (if it +had been in kernel mode). +<h3>NOTES</h3> +<p> +By way of comparison, the <strong>thread_suspend</strong> function keeps +the target thread +from executing any further instructions at the user level, including +the return +from a system call. The <strong>thread_get_state</strong> function +returns the thread's user +state, while <strong>thread_set_state</strong> allows modification of the user state. +<p> +A problem occurs if a suspended thread had been executing within a system +call. In this case, the thread has, not only a user state, but +an associated kernel +state. (The kernel state cannot be changed with <strong>thread_set_state</strong>.) +As a result, +when the thread resumes, the system call can return, producing a change in the +user state and, possibly, user memory. +<p> +For a thread executing within a system call, <strong>thread_abort</strong> +aborts the kernel call +from the thread's point of view. Specifically, it resets the +kernel state so that the +thread will resume execution at the system call return, with the return code +value set to one of the interrupted codes. The system call itself +may be completed +entirely, aborted entirely or be partially completed, depending on when the +abort is received. As a result, if the thread's user state has +been modified by +<strong>thread_set_state</strong>, it will not be altered un-predictably +by any unexpected +system call side effects. +<p> +For example, to simulate a POSIX signal, use the following sequence of calls: +<dl> +<dd> +<strong>thread_suspend</strong>\(emTo stop the thread. +<dd> +<strong>thread_abort</strong>\(emTo interrupt any system call in progress +and set the return +value to "interrupted". Because the thread is already stopped, it will not +return to user code. +<dd> +<strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a +procedure call to the signal handler. +<dd> +<strong>thread_resume</strong>\(emTo resume execution at the signal handler. +If the thread's +stack is set up correctly, the thread can return to the interrupted system call. +Note that the code to push an extra stack frame and change the registers is +highly machine dependent. +</dl> +<h3>CAUTIONS</h3> +<p> +As a rule, do not use <strong>thread_abort</strong> on a non-suspended +thread. This operation +is very risky because it is difficult to know which system trap, if any, is +executing and whether an interrupt return will result in some +useful action by the +thread. +<p> +<strong>thread_abort</strong> will abort any non-atomic operation (such as a multi-page +<strong>memory_object_data_supply</strong>) at an arbitrary point in a non-restartable +way. Such problems can be avoided by using <strong>thread_abort_safely</strong>. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_EXCEPTION_PROTECTED</strong> +<dd> +The thread is processing a protected exception. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_msg.html"><strong>mach_msg</strong></a>, +<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="thread_set_state.html"><strong>thread_set_state</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>, +<a href="thread_terminate.html"><strong>thread_terminate</strong></a>, +<a href="thread_abort_safely.html"><strong>thread_abort_safely</strong></a>, +<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>. diff --git a/osfmk/man/thread_abort_safely.html b/osfmk/man/thread_abort_safely.html index 7dc47fc15..e8f09cea3 100755 --- a/osfmk/man/thread_abort_safely.html +++ b/osfmk/man/thread_abort_safely.html @@ -1 +1,134 @@ -<h2>thread_abort_safely</h2> <hr> <p> <strong>Function</strong> - Abort a thread, restartably. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_abort_safely</strong> <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_thread</var> <dd> [in thread send right] The thread to be aborted. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_abort_safely</strong> function aborts page faults and any message primitive calls in use by <var>target_thread</var>. Scheduling depressions and clock sleeps are also aborted. The call returns a code indicating that it was interrupted. The call is interrupted even if the thread (or the task containing it) is suspended. If it is suspended, the thread receives the interrupt when it resumes. <p> If its state is not modified before it resumes, the thread will retry an aborted page fault. The Mach message trap returns either <strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending on whether the send or the receive side was interrupted. Note, though, that the Mach message trap is contained within the <strong>mach_msg</strong> library routine, which, by default, retries interrupted message calls. <p> The basic purpose of <strong>thread_abort_safely</strong> is to let one thread cleanly stop another thread (<var>target_thread</var>). The target thread is stopped in such a manner that its future execution can be controlled in a predictable way. When <strong>thread_abort_safely</strong> returns (if successful), the target thread will appear to have just returned from the kernel (if it had been in kernel mode). <h3>NOTES</h3> <p> By way of comparison, the <strong>thread_suspend</strong> function keeps the target thread from executing any further instructions at the user level, including the return from a system call. The <strong>thread_get_state</strong> function returns the thread's user state, while <strong>thread_set_state</strong> allows modification of the user state. <p> A problem occurs if a suspended thread had been executing within a system call. In this case, the thread has, not only a user state, but an associated kernel state. (The kernel state cannot be changed with <strong>thread_set_state</strong>.) As a result, when the thread resumes, the system call can return, producing a change in the user state and, possibly, user memory. <p> For a thread executing within a system call, <strong>thread_abort_safely</strong> aborts the kernel call from the thread's point of view. Specifically, it resets the kernel state so that the thread will resume execution at the system call return, with the return code value set to one of the interrupted codes. The system call itself may completed entirely, aborted entirely or be partially completed, depending on when the abort is received. As a result, if the thread's user state has been modified by <strong>thread_set_state</strong>, it will not be altered un-predictably by any unexpected system call side effects. <p> For example, to simulate a POSIX signal, use the following sequence of calls: <dl> <dd> <strong>thread_suspend</strong>\(emTo stop the thread. <dd> <strong>thread_abort_safely</strong>\(emTo interrupt any system call in progress and set the return value to "interrupted". Because the thread is already stopped, it will not return to user code. <dd> <strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a procedure call to the signal handler. <dd> <strong>thread_resume</strong>\(emTo resume execution at the signal handler. If the thread's stack is set up correctly, the thread can return to the interrupted system call. Note that the code to push an extra stack frame and change the registers is highly machine dependent. </dl> <h3>CAUTIONS</h3> <p> As a rule, do not use <strong>thread_abort_safely</strong> on a non-suspended thread. This operation is very risky because it is difficult to know which system trap, if any, is executing and whether an interrupt return will result in some useful action by the thread. <p> <strong>thread_abort_safely</strong> will not abort any non-atomic operation (such as a multi-page <strong>memory_object_data_supply</strong> or exception processing) but will return an error instead. The caller of this function must then allow the thread to resume and attempt to abort it later. If the thread must be aborted, even if doing so would abort any non-atomic operations, <strong>thread_abort</strong> would be used. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_FAILURE</strong> <dd> The thread is in the middle of a non-restartable operation. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="thread_get_state.html"><strong>thread_get_state</strong></a>, <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="thread_set_state.html"><strong>thread_set_state</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>, <a href="thread_terminate.html"><strong>thread_terminate</strong></a>, <a href="thread_abort.html"><strong>thread_abort</strong></a>. \ No newline at end of file +<h2>thread_abort_safely</h2> +<hr> +<p> +<strong>Function</strong> - Abort a thread, restartably. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_abort_safely</strong> + <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_thread</var> +<dd> +[in thread send right] +The thread to be aborted. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_abort_safely</strong> function aborts page faults and any message +primitive calls in use by <var>target_thread</var>. Scheduling depressions +and clock sleeps are +also aborted. The call returns a code indicating that it was +interrupted. The call +is interrupted even if the thread (or the task containing it) +is suspended. If it is +suspended, the thread receives the interrupt when it resumes. +<p> +If its state is not modified before it resumes, the thread will +retry an aborted +page fault. The Mach message trap returns either +<strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending +on whether the send or the +receive side was interrupted. Note, though, that the Mach message trap is +contained within the <strong>mach_msg</strong> library routine, which, +by default, retries +interrupted message calls. +<p> +The basic purpose of <strong>thread_abort_safely</strong> is to let +one thread cleanly stop +another thread (<var>target_thread</var>). The target thread is stopped +in such a manner that +its future execution can be controlled in a predictable way. When +<strong>thread_abort_safely</strong> returns (if successful), the target +thread will appear to have just +returned from the kernel (if it had been in kernel mode). +<h3>NOTES</h3> +<p> +By way of comparison, the <strong>thread_suspend</strong> function keeps +the target thread +from executing any further instructions at the user level, including +the return +from a system call. The <strong>thread_get_state</strong> function +returns the thread's user +state, while <strong>thread_set_state</strong> allows modification of the user state. +<p> +A problem occurs if a suspended thread had been executing within a system +call. In this case, the thread has, not only a user state, but +an associated kernel +state. (The kernel state cannot be changed with <strong>thread_set_state</strong>.) +As a result, +when the thread resumes, the system call can return, producing a change in the +user state and, possibly, user memory. +<p> +For a thread executing within a system call, <strong>thread_abort_safely</strong> +aborts the +kernel call from the thread's point of view. Specifically, it +resets the kernel state so +that the thread will resume execution at the system call return, +with the return +code value set to one of the interrupted codes. The system call itself may +completed entirely, aborted entirely or be partially completed, +depending on when +the abort is received. As a result, if the thread's user state +has been modified by +<strong>thread_set_state</strong>, it will not be altered un-predictably +by any unexpected +system call side effects. +<p> +For example, to simulate a POSIX signal, use the following sequence of calls: +<dl> +<dd> +<strong>thread_suspend</strong>\(emTo stop the thread. +<dd> +<strong>thread_abort_safely</strong>\(emTo interrupt any system call in +progress and set the +return value to "interrupted". Because the thread is already stopped, it will +not return to user code. +<dd> +<strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a +procedure call to the signal handler. +<dd> +<strong>thread_resume</strong>\(emTo resume execution at the signal handler. +If the thread's +stack is set up correctly, the thread can return to the interrupted +system call. +Note that the code to push an extra stack frame and change the registers is +highly machine dependent. +</dl> +<h3>CAUTIONS</h3> +<p> +As a rule, do not use <strong>thread_abort_safely</strong> on a non-suspended +thread. This +operation is very risky because it is difficult to know which +system trap, if any, is +executing and whether an interrupt return will result in some useful action by +the thread. +<p> +<strong>thread_abort_safely</strong> will not abort any non-atomic operation +(such as a +multi-page <strong>memory_object_data_supply</strong> or exception processing) +but will return an +error instead. The caller of this function must then allow the +thread to resume +and attempt to abort it later. If the thread must be aborted, +even if doing so +would abort any non-atomic operations, <strong>thread_abort</strong> would be used. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_FAILURE</strong> +<dd> +The thread is in the middle of a non-restartable operation. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_msg.html"><strong>mach_msg</strong></a>, +<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="thread_set_state.html"><strong>thread_set_state</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>, +<a href="thread_terminate.html"><strong>thread_terminate</strong></a>, +<a href="thread_abort.html"><strong>thread_abort</strong></a>. diff --git a/osfmk/man/thread_activation_create.html b/osfmk/man/thread_activation_create.html index 3907322d5..7a47b81af 100755 --- a/osfmk/man/thread_activation_create.html +++ b/osfmk/man/thread_activation_create.html @@ -1 +1,79 @@ -<h2>thread_activation_create</h2> <hr> <p> <strong>Function</strong> - Create a thread activation. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_activation_create</strong> <strong>(task_t</strong> <var>task</var>, <strong>mach_port_name_t</strong> <var>RPC_port</var>, <strong>vm_offset_t</strong> <var>user_stack</var>, <strong>vm_size_t</strong> <var>stack_size</var>, <strong>thread_act_t</strong> <var>thread_act_t</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>task</var> <dd> [in task send right] The port for the task that is to contain the new thread activation. <p> <dt> <var>RPC_port</var> <dd> [in receive right] A receive right held by the task, or a port set in the task. <p> <dt> <var>user_stack</var> <dd> [in scalar] The virtual address in the task to be used as the starting ad- dress of the user-level stack. <p> <dt> <var>new_act</var> <dd> [out thread send right] The kernel-assigned name for the new thread ac- tivation. </dl> <h3>DESCRIPTION</h3> <p> The thread_activation_create function creates a thread activation, or "empty thread", into which a client thread shuttle can migrate during RPC. The RPC_port must name ei- ther a receive right held by the task, or a port set in the task. The new thread activation will be added to a pool of activations attached to this port (or port set). Incoming RPC's targeted at the port (or one of the ports in the set) can use any of the activations in the pool. That is, the client thread shuttle will migrate into the specified server task, take one of the thread activations out of the pool, and join up with it for the duration of the RPC. The shuttle will migrate back to the original client activation at the end of the RPC. If no thread activations are in the pool, RPC will be blocked until one is created in the pool, or an existing one finishes its RPC and returns to the pool. The new thread activation will begin each RPC using the stack pointer specified by user_stack. The kernel neither knows nor cares how big the specified stack is. When a short-circuited RPC (or mach_rpc) is invoked on a port created with mach_port_allocate_subsystem, the RPC will begin execution in the subsystem server at the work function address specified by the port and routine number and looked up in the associated subsystem data. <h3>NOTES</h3> <p> The following calls targeted at a thread_act port may _not_ be called on an empty thread_act (and will return KERN_INVALID_ARGUMENT if they are called with one): thread_abort thread_abort_safely thread_depress_abort thread_info thread_wire In addition, if thread_switch is called with an empty thread_act as its first argument, the argument will be ignored (i.e., the function will behave as if a zero-valued argument had been given). <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>, \ No newline at end of file +<h2>thread_activation_create</h2> +<hr> +<p> +<strong>Function</strong> - Create a thread activation. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_activation_create</strong> + <strong>(task_t</strong> <var>task</var>, + <strong>mach_port_name_t</strong> <var>RPC_port</var>, + <strong>vm_offset_t</strong> <var>user_stack</var>, + <strong>vm_size_t</strong> <var>stack_size</var>, + <strong>thread_act_t</strong> <var>thread_act_t</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>task</var> +<dd> +[in task send right] The port for the task that is to contain the new +thread activation. +<p> +<dt> <var>RPC_port</var> +<dd> +[in receive right] A receive right held by the task, or a port set in the +task. +<p> +<dt> <var>user_stack</var> +<dd> +[in scalar] The virtual address in the task to be used as the starting ad- +dress of the user-level stack. +<p> +<dt> <var>new_act</var> +<dd> +[out thread send right] The kernel-assigned name for the new thread ac- +tivation. +</dl> +<h3>DESCRIPTION</h3> +<p> +The thread_activation_create function creates a thread activation, or +"empty thread", into which a client thread shuttle can migrate during +RPC. The RPC_port must name ei- ther a receive right held by the +task, or a port set in the task. The new thread activation will be +added to a pool of activations attached to this port (or port set). +Incoming RPC's targeted at the port (or one of the ports in the set) +can use any of the activations in the pool. That is, the client +thread shuttle will migrate into the specified server task, take one +of the thread activations out of the pool, and join up with it for the +duration of the RPC. The shuttle will migrate back to the original +client activation at the end of the RPC. If no thread activations are +in the pool, RPC will be blocked until one is created in the pool, or +an existing one finishes its RPC and returns to the pool. +The new thread activation will begin each RPC using the stack pointer +specified by user_stack. The kernel neither knows nor cares how big +the specified stack is. +When a short-circuited RPC (or mach_rpc) is invoked on a port created +with mach_port_allocate_subsystem, the RPC will begin execution in the +subsystem server at the work function address specified by the port +and routine number and looked up in the associated subsystem data. +<h3>NOTES</h3> +<p> +The following calls targeted at a thread_act port may _not_ be called +on an empty thread_act (and will return KERN_INVALID_ARGUMENT if +they are called with one): +thread_abort +thread_abort_safely +thread_depress_abort +thread_info +thread_wire +In addition, if thread_switch is called with an empty thread_act as +its first argument, the argument will be ignored (i.e., the function +will behave as if a zero-valued argument had been given). +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>, diff --git a/osfmk/man/thread_assign.html b/osfmk/man/thread_assign.html index a5e767eb0..fc10265ad 100755 --- a/osfmk/man/thread_assign.html +++ b/osfmk/man/thread_assign.html @@ -1 +1,42 @@ -<h2>thread_assign</h2> <hr> <p> <strong>Function</strong> - Assign a thread to a processor set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_assign</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>processor_set_t</strong> <var>processor_set</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] The thread to be assigned. <p> <dt> <var>processor_set</var> <dd> [in processor-set-control send right] The control port for the processor set into which the thread is to be assigned. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_assign</strong> function assigns <strong>thread</strong> to the set <var>processor_set</var>. After the assignment is completed, the thread executes only on processors that are assigned to that processor set. Any previous assignment of the thread is nullified. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_assign_default.html"><strong>thread_assign_default</strong></a>, <a href="thread_get_assignment.html"><strong>thread_get_assignment</strong></a>, <a href="processor_set_create.html"><strong>processor_set_create</strong></a>, <a href="processor_set_info.html"><strong>processor_set_info</strong></a>, <a href="task_assign.html"><strong>task_assign</strong></a>. \ No newline at end of file +<h2>thread_assign</h2> +<hr> +<p> +<strong>Function</strong> - Assign a thread to a processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_assign</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>processor_set_t</strong> <var>processor_set</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread to be assigned. +<p> +<dt> <var>processor_set</var> +<dd> +[in processor-set-control send right] +The control port for the processor +set into which the thread is to be assigned. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_assign</strong> function assigns <strong>thread</strong> to the set +<var>processor_set</var>. After the +assignment is completed, the thread executes only on processors +that are assigned +to that processor set. Any previous assignment of the thread is nullified. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_assign_default.html"><strong>thread_assign_default</strong></a>, +<a href="thread_get_assignment.html"><strong>thread_get_assignment</strong></a>, +<a href="processor_set_create.html"><strong>processor_set_create</strong></a>, +<a href="processor_set_info.html"><strong>processor_set_info</strong></a>, +<a href="task_assign.html"><strong>task_assign</strong></a>. diff --git a/osfmk/man/thread_assign_default.html b/osfmk/man/thread_assign_default.html index 76e8114f5..0ab0c1548 100755 --- a/osfmk/man/thread_assign_default.html +++ b/osfmk/man/thread_assign_default.html @@ -1 +1,40 @@ -<h2>thread_assign_default</h2> <hr> <p> <strong>Function</strong> - Assign a thread to the default processor set. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_assign_default</strong> <strong>(thread_act_t</strong> <var>thread</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] The thread to be assigned. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_assign_default</strong> function assigns <var>thread</var> to the default processor set. After the assignment is completed, the thread executes only on processors that are assigned to that processor set. Any previous assignment of the thread is nullified. <h3>NOTES</h3> <p> This variant of <strong>thread_assign</strong> exists because the control port for the default processor set is privileged, and therefore not available to most tasks. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_assign.html"><strong>thread_assign</strong></a>, <a href="thread_get_assignment.html"><strong>thread_get_assignment</strong></a>, <a href="processor_set_create.html"><strong>processor_set_create</strong></a>, <a href="processor_set_info.html"><strong>processor_set_info</strong></a>, <a href="task_assign.html"><strong>task_assign</strong></a>. \ No newline at end of file +<h2>thread_assign_default</h2> +<hr> +<p> +<strong>Function</strong> - Assign a thread to the default processor set. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_assign_default</strong> + <strong>(thread_act_t</strong> <var>thread</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread to be assigned. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_assign_default</strong> function assigns <var>thread</var> to +the default processor set. +After the assignment is completed, the thread executes only on processors that +are assigned to that processor set. Any previous assignment of the thread is +nullified. +<h3>NOTES</h3> +<p> +This variant of <strong>thread_assign</strong> exists because the control +port for the default +processor set is privileged, and therefore not available to most tasks. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_assign.html"><strong>thread_assign</strong></a>, +<a href="thread_get_assignment.html"><strong>thread_get_assignment</strong></a>, +<a href="processor_set_create.html"><strong>processor_set_create</strong></a>, +<a href="processor_set_info.html"><strong>processor_set_info</strong></a>, +<a href="task_assign.html"><strong>task_assign</strong></a>. diff --git a/osfmk/man/thread_basic_info.html b/osfmk/man/thread_basic_info.html index c852420d0..a39f88a2f 100755 --- a/osfmk/man/thread_basic_info.html +++ b/osfmk/man/thread_basic_info.html @@ -1 +1,100 @@ -<h2>thread_basic_info</h2> <hr> <p> <strong>Structure</strong> - Defines basic information for a thread. <h3>SYNOPSIS</h3> <pre> <strong>struct thread_basic_info</strong> <strong>{</strong> <strong>time_value_t</strong> <var>user_time</var><strong>;</strong> <strong>time_value_t</strong> <var>system_time</var><strong>;</strong> <strong>integer_t</strong> <var>cpu_usage</var><strong>;</strong> <strong>policy_t</strong> <var>policy</var><strong>;</strong> <strong>integer_t</strong> <var>run_state</var><strong>;</strong> <strong>integer_t</strong> <var>flags</var><strong>;</strong> <strong>integer_t</strong> <var>suspend_count</var><strong>;</strong> <strong>integer_t</strong> <var>sleep_time</var><strong>;</strong> <strong>};</strong> <strong>typedef struct thread_basic_info* thread_basic_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>user_time</var> <dd> The total user run time for the thread. <p> <dt> <var>system_time</var> <dd> The total system run time for the thread. <p> <dt> <var>cpu_usage</var> <dd> Scaled <strong>CPU</strong> usage percentage for the thread. <p> <dt> <var>policy</var> <dd> Scheduling policy in effect <p> <dt> <var>run_state</var> <dd> The thread's run state. Possible values are: <dl> <p> <dt> <strong>TH_STATE_RUNNING</strong> <dd> The thread is running normally. <p> <dt> <strong>TH_STATE_STOPPED</strong> <dd> The thread is stopped. <p> <dt> <strong>TH_STATE_WAITING</strong> <dd> The thread is waiting normally. <p> <dt> <strong>TH_STATE_UNINTERRUPTIBLE</strong> <dd> The thread is in an un-interruptible wait state. <p> <dt> <strong>TH_STATE_HALTED</strong> <dd> The thread is halted at a clean point. </dl> <p> <dt> <var>flags</var> <dd> Swap/idle flags for the thread. Possible values are: <dl> <p> <dt> <strong>TH_FLAGS_SWAPPED</strong> <dd> The thread is swapped out. <p> <dt> <strong>TH_FLAGS_IDLE</strong> <dd> The thread is an idle thread. </dl> <p> <dt> <var>suspend_count</var> <dd> The current suspend count for the thread. <p> <dt> <var>sleep_time</var> <dd> The number of seconds that the thread has been sleeping. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_basic_info</strong> structure defines the basic information array for threads. The <strong>thread_info</strong> function returns this array for a specified thread. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_info.html"><strong>thread_info</strong></a>. <p> Data Structures: <a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, <a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, <a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. \ No newline at end of file +<h2>thread_basic_info</h2> +<hr> +<p> +<strong>Structure</strong> - Defines basic information for a thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct thread_basic_info</strong> +<strong>{</strong> + <strong>time_value_t</strong> <var>user_time</var><strong>;</strong> + <strong>time_value_t</strong> <var>system_time</var><strong>;</strong> + <strong>integer_t</strong> <var>cpu_usage</var><strong>;</strong> + <strong>policy_t</strong> <var>policy</var><strong>;</strong> + <strong>integer_t</strong> <var>run_state</var><strong>;</strong> + <strong>integer_t</strong> <var>flags</var><strong>;</strong> + <strong>integer_t</strong> <var>suspend_count</var><strong>;</strong> + <strong>integer_t</strong> <var>sleep_time</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct thread_basic_info* thread_basic_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>user_time</var> +<dd> +The total user run time for the thread. + <p> +<dt> <var>system_time</var> +<dd> +The total system run time for the thread. + <p> +<dt> <var>cpu_usage</var> +<dd> +Scaled <strong>CPU</strong> usage percentage for the thread. + <p> +<dt> <var>policy</var> +<dd> +Scheduling policy in effect + <p> +<dt> <var>run_state</var> +<dd> +The thread's run state. Possible values are: +<dl> + <p> +<dt> <strong>TH_STATE_RUNNING</strong> +<dd> +The thread is running normally. + <p> +<dt> <strong>TH_STATE_STOPPED</strong> +<dd> +The thread is stopped. + <p> +<dt> <strong>TH_STATE_WAITING</strong> +<dd> +The thread is waiting normally. + <p> +<dt> <strong>TH_STATE_UNINTERRUPTIBLE</strong> +<dd> +The thread is in an un-interruptible wait state. + <p> +<dt> <strong>TH_STATE_HALTED</strong> +<dd> +The thread is halted at a clean point. +</dl> + <p> +<dt> <var>flags</var> +<dd> +Swap/idle flags for the thread. Possible values are: +<dl> + <p> +<dt> <strong>TH_FLAGS_SWAPPED</strong> +<dd> +The thread is swapped out. + <p> +<dt> <strong>TH_FLAGS_IDLE</strong> +<dd> +The thread is an idle thread. +</dl> + <p> +<dt> <var>suspend_count</var> +<dd> +The current suspend count for the thread. + <p> +<dt> <var>sleep_time</var> +<dd> +The number of seconds that the thread has been sleeping. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_basic_info</strong> structure defines the basic information +array for threads. +The <strong>thread_info</strong> function returns this array for a specified thread. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_info.html"><strong>thread_info</strong></a>. +<p> +Data Structures: +<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, +<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, +<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. diff --git a/osfmk/man/thread_create.html b/osfmk/man/thread_create.html index 135b1c5bd..91ec23a76 100755 --- a/osfmk/man/thread_create.html +++ b/osfmk/man/thread_create.html @@ -1 +1,58 @@ -<h2>thread_create</h2> <hr> <p> <strong>Function</strong> - Create a thread within a task. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_create</strong> <strong>(task_t</strong> <var>parent_task</var>, <strong>thread_act_t</strong> <var>child_thread</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>parent_task</var> <dd> [in task send right] The port for the task that is to contain the new thread. <p> <dt> <var>child_thread</var> <dd> [out thread send right] The kernel-assigned name for the new thread. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_create</strong> function creates a new thread within <var>parent_task</var>. The new thread has a suspend count of one and no processor state. <p> The new thread holds a send right for its thread kernel port. A send right for the thread's kernel port is also returned to the calling task or thread in <var>child_thread</var>. The new thread's exception ports are set to <strong>MACH_PORT_NULL</strong>. <h3>NOTES</h3> <p> To get a new thread running, first use <strong>thread_set_state</strong> to set a processor state for the thread. Then, use <strong>thread_resume</strong> to schedule the thread for execution. Alternately, use <strong>thread_create_running</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="task_threads.html"><strong>task_threads</strong></a>, <a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>, <a href="thread_get_state.html"><strong>thread_get_state</strong></a>, <a href="thread_resume.html"><strong>thread_resume</strong></a>, <a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>, <a href="thread_set_state.html"><strong>thread_set_state</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>, <a href="thread_terminate.html"><strong>thread_terminate</strong></a>, <a href="thread_create_running.html"><strong>thread_create_running</strong></a>. \ No newline at end of file +<h2>thread_create</h2> +<hr> +<p> +<strong>Function</strong> - Create a thread within a task. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_create</strong> + <strong>(task_t</strong> <var>parent_task</var>, + <strong>thread_act_t</strong> <var>child_thread</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>parent_task</var> +<dd> +[in task send right] +The port for the task that is to contain the new +thread. +<p> +<dt> <var>child_thread</var> +<dd> +[out thread send right] +The kernel-assigned name for the new thread. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_create</strong> function creates a new thread within +<var>parent_task</var>. The new thread has a suspend count of one and +no processor state. +<p> +The new thread holds a send right for its thread kernel port. +A send right for the +thread's kernel port is also returned to the calling task or +thread in <var>child_thread</var>. +The new thread's exception ports are set to <strong>MACH_PORT_NULL</strong>. +<h3>NOTES</h3> +<p> +To get a new thread running, first use <strong>thread_set_state</strong> +to set a processor state +for the thread. Then, use <strong>thread_resume</strong> to schedule +the thread for execution. +Alternately, use <strong>thread_create_running</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="task_threads.html"><strong>task_threads</strong></a>, +<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>, +<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, +<a href="thread_resume.html"><strong>thread_resume</strong></a>, +<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>, +<a href="thread_set_state.html"><strong>thread_set_state</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>, +<a href="thread_terminate.html"><strong>thread_terminate</strong></a>, +<a href="thread_create_running.html"><strong>thread_create_running</strong></a>. diff --git a/osfmk/man/thread_create_running.html b/osfmk/man/thread_create_running.html index bab1033a7..998c92fa2 100755 --- a/osfmk/man/thread_create_running.html +++ b/osfmk/man/thread_create_running.html @@ -1 +1,73 @@ -<h2>thread_create_running</h2> <hr> <p> <strong>Function</strong> - Optimized creation of a running thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_create_running</strong> <strong>(task_t</strong> <var>parent_task</var>, <strong>thread_state_flavor_t</strong> <var>flavor</var>, <strong>thread_state_t</strong> <var>state</var>, <strong>thread_act_t</strong> <var>child_thread</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>parent_task</var> <dd> [in task send right] The port for the task that is to contain the new thread. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of state to establish. Valid values correspond to supported machine architecture features. <p> <dt> <var>state</var> <dd> [pointer to in structure] State information for the specified thread. <p> <dt> <var>child_thread</var> <dd> [out thread send right] The kernel-assigned name for the new thread. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_create_running</strong> function creates a new thread within <var>parent_task</var>. The new thread has is not suspended. Its initial state is given by <var>state</var>. <var>flavor</var> specifies the type of state to set. <p> The format of the state to set is machine specific; it is defined in \*L<mach/thread_status.h>\*O. <p> The new thread holds a send right for its thread kernel port. A send right for the thread's kernel port is also returned to the calling task or thread in <var>child_thread</var>. The new thread's exception ports are set to <strong>MACH_PORT_NULL</strong>. <h3>NOTES</h3> <p> This is an optimized form of the sequence: <strong>thread_create</strong>, <strong>thread_set_state</strong> and <strong>thread_resume</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="task_threads.html"><strong>task_threads</strong></a>, <a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>, <a href="thread_get_state.html"><strong>thread_get_state</strong></a>, <a href="thread_resume.html"><strong>thread_resume</strong></a>, <a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>, <a href="thread_set_state.html"><strong>thread_set_state</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>, <a href="thread_terminate.html"><strong>thread_terminate</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>. \ No newline at end of file +<h2>thread_create_running</h2> +<hr> +<p> +<strong>Function</strong> - Optimized creation of a running thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_create_running</strong> + <strong>(task_t</strong> <var>parent_task</var>, + <strong>thread_state_flavor_t</strong> <var>flavor</var>, + <strong>thread_state_t</strong> <var>state</var>, + <strong>thread_act_t</strong> <var>child_thread</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>parent_task</var> +<dd> +[in task send right] +The port for the task that is to contain the new +thread. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of state to establish. Valid values correspond to +supported machine architecture features. +<p> +<dt> <var>state</var> +<dd> +[pointer to in structure] +State information for the specified thread. +<p> +<dt> <var>child_thread</var> +<dd> +[out thread send right] +The kernel-assigned name for the new thread. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_create_running</strong> function creates a new thread +within <var>parent_task</var>. +The new thread has is not suspended. Its initial state is given +by <var>state</var>. <var>flavor</var> specifies the type of state to set. +<p> +The format of the state to set is machine specific; it is defined in +\*L<mach/thread_status.h>\*O. +<p> +The new thread holds a send right for its thread kernel port. +A send right for the +thread's kernel port is also returned to the calling task or +thread in <var>child_thread</var>. +The new thread's exception ports are set to <strong>MACH_PORT_NULL</strong>. +<h3>NOTES</h3> +<p> +This is an optimized form of the sequence: <strong>thread_create</strong>, +<strong>thread_set_state</strong> +and <strong>thread_resume</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="task_threads.html"><strong>task_threads</strong></a>, +<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>, +<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, +<a href="thread_resume.html"><strong>thread_resume</strong></a>, +<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>, +<a href="thread_set_state.html"><strong>thread_set_state</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>, +<a href="thread_terminate.html"><strong>thread_terminate</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>. diff --git a/osfmk/man/thread_depress_abort.html b/osfmk/man/thread_depress_abort.html index 498d93a3e..bd08638b4 100755 --- a/osfmk/man/thread_depress_abort.html +++ b/osfmk/man/thread_depress_abort.html @@ -1 +1,29 @@ -<h2>thread_depress_abort</h2> <hr> <p> <strong>Function</strong> - Cancel thread scheduling depression. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_depress_abort</strong> <strong>(thread_act_t</strong> <var>thread</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] Thread whose scheduling depression is canceled. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_depress_abort</strong> function cancels any scheduling depression effective for <var>thread</var> caused by a <strong>thread_switch</strong> call. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_abort.html"><strong>thread_abort</strong></a>, <a href="thread_switch.html"><strong>thread_switch</strong></a>. \ No newline at end of file +<h2>thread_depress_abort</h2> +<hr> +<p> +<strong>Function</strong> - Cancel thread scheduling depression. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_depress_abort</strong> + <strong>(thread_act_t</strong> <var>thread</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +Thread whose scheduling depression is canceled. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_depress_abort</strong> function cancels any scheduling depression +effective for <var>thread</var> caused by a <strong>thread_switch</strong> call. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_abort.html"><strong>thread_abort</strong></a>, +<a href="thread_switch.html"><strong>thread_switch</strong></a>. diff --git a/osfmk/man/thread_get_assignment.html b/osfmk/man/thread_get_assignment.html index ad6c4171c..c29410d09 100755 --- a/osfmk/man/thread_get_assignment.html +++ b/osfmk/man/thread_get_assignment.html @@ -1 +1,40 @@ -<h2>thread_get_assignment</h2> <hr> <p> <strong>Function</strong> - Return the processor set to which a thread is assigned. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_get_assignment</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>processor_set_name_t</strong> <var>processor_set</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] The thread whose assignment is desired. <p> <dt> <var>processor_set</var> <dd> [out processor-set-name send right] The name port for the processor set into which the thread is assigned. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_get_assignment</strong> function returns the name port to the processor set to which <var>thread</var> is currently assigned. This port can only be used to obtain information about the processor set. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_assign.html"><strong>thread_assign</strong></a>, <a href="thread_assign_default.html"><strong>thread_assign_default</strong></a>, <a href="processor_set_create.html"><strong>processor_set_create</strong></a>, <a href="processor_set_info.html"><strong>processor_set_info</strong></a>, <a href="task_assign.html"><strong>task_assign</strong></a>. \ No newline at end of file +<h2>thread_get_assignment</h2> +<hr> +<p> +<strong>Function</strong> - Return the processor set to which a thread is assigned. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_get_assignment</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>processor_set_name_t</strong> <var>processor_set</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread whose assignment is desired. +<p> +<dt> <var>processor_set</var> +<dd> +[out processor-set-name send right] +The name port for the processor +set into which the thread is assigned. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_get_assignment</strong> function returns the name +port to the processor set to which <var>thread</var> is currently assigned. +This port can only be used to obtain information about the processor set. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_assign.html"><strong>thread_assign</strong></a>, +<a href="thread_assign_default.html"><strong>thread_assign_default</strong></a>, +<a href="processor_set_create.html"><strong>processor_set_create</strong></a>, +<a href="processor_set_info.html"><strong>processor_set_info</strong></a>, +<a href="task_assign.html"><strong>task_assign</strong></a>. diff --git a/osfmk/man/thread_get_exception_ports.html b/osfmk/man/thread_get_exception_ports.html index 70fbb6726..d726de0af 100755 --- a/osfmk/man/thread_get_exception_ports.html +++ b/osfmk/man/thread_get_exception_ports.html @@ -1 +1,141 @@ -<h2>thread_get_exception_ports</h2> <hr> <p> <strong>Function</strong> - Return a send right to an exception port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_get_exception_ports</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>exception_mask_t</strong> <var>exception_types</var>, <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>, <strong>old_exception_masks</strong> <var>old_exception_count</var>, <strong>exception_port_array_t</strong> <var>old_exception_ports</var>, <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>, <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] The thread for which to return the exception ports. <p> <dt> <var>exception_types</var> <dd> [in scalar] A flag word indicating the types of exceptions for which the exception ports are desired: <dl> <p> <dt> <strong>EXC_MASK_BAD_ACCESS</strong> <dd> Could not access memory. <p> <dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> <dd> Instruction failed. Illegal or undefined instruction or operand. <p> <dt> <strong>EXC_MASK_ARITHMETIC</strong> <dd> Arithmetic exception. <p> <dt> <strong>EXC_MASK_EMULATION</strong> <dd> Emulation instruction. Emulation support instruction encountered. <p> <dt> <strong>EXC_MASK_SOFTWARE</strong> <dd> Software generated exception. <p> <dt> <strong>EXC_MASK_BREAKPOINT</strong> <dd> Trace, breakpoint, etc. <p> <dt> <strong>EXC_MASK_SYSCALL</strong> <dd> System call requested. <p> <dt> <strong>EXC_MASK_MACH_SYSCALL</strong> <dd> System call with a number in the Mach call range requested. </dl> <p> <dt> <var>old_exception_masks</var> <dd> [out array of <var>exception_mask_t</var>] An array, each element being a mask specifying for which exception types the corresponding element of the other arrays apply. <p> <dt> <var>old_exception_count</var> <dd> [pointer to in/out scalar] On input, the maximum size of the array buffers; on output, the number of returned <exception type mask, exception port, behavior, flavor> sets returned. <p> <dt> <var>old_exception_ports</var> <dd> [out array of exception send rights] The returned exception ports. <p> <dt> <var>old_behaviors</var> <dd> [out array of <var>exception_behavior_t</var>] The type of exception message to be sent. Defined types are: <dl> <p> <dt> <strong>EXCEPTION_DEFAULT</strong> <dd> Send a <strong>catch_exception_raise</strong> message including the thread identity. <p> <dt> <strong>EXCEPTION_STATE</strong> <dd> Send a <strong>catch_exception_raise_state</strong> message including the thread state. <p> <dt> <strong>EXCEPTION_STATE_IDENTITY</strong> <dd> Send a <strong>catch_exception_raise_state_identity</strong> message including the thread identity and state. </dl> <p> <dt> <var>old_flavors</var> <dd> [out array of <var>thread_state_flavor_t</var>] The type of state to be sent with the exception message. These types are defined in \*L<mach/thread_states.h>\*O. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_get_exception_ports</strong> function returns send rights for a specified set of exception ports belonging to <var>thread</var>. The call returns a set of quadruples <exception type mask, exception port, behavior, flavor> for each unique set of <exception port, behavior, flavor> in effect for the thread where the exception type mask indicates for which exception types the other values apply. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_EXCEPTION_PROTECTED</strong> <dd> One of the requested exception ports is protected and cannot be returned. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>, <a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, <a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, <a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, <a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>. \ No newline at end of file +<h2>thread_get_exception_ports</h2> +<hr> +<p> +<strong>Function</strong> - Return a send right to an exception port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_get_exception_ports</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>exception_mask_t</strong> <var>exception_types</var>, + <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>, + <strong>old_exception_masks</strong> <var>old_exception_count</var>, + <strong>exception_port_array_t</strong> <var>old_exception_ports</var>, + <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>, + <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread for which to return the exception +ports. +<p> +<dt> <var>exception_types</var> +<dd> +[in scalar] +A flag word indicating the types of exceptions for which the +exception ports are desired: +<dl> +<p> +<dt> <strong>EXC_MASK_BAD_ACCESS</strong> +<dd> +Could not access memory. +<p> +<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> +<dd> +Instruction failed. Illegal or undefined instruction or operand. +<p> +<dt> <strong>EXC_MASK_ARITHMETIC</strong> +<dd> +Arithmetic exception. +<p> +<dt> <strong>EXC_MASK_EMULATION</strong> +<dd> +Emulation instruction. Emulation support instruction +encountered. +<p> +<dt> <strong>EXC_MASK_SOFTWARE</strong> +<dd> +Software generated exception. +<p> +<dt> <strong>EXC_MASK_BREAKPOINT</strong> +<dd> +Trace, breakpoint, etc. +<p> +<dt> <strong>EXC_MASK_SYSCALL</strong> +<dd> +System call requested. +<p> +<dt> <strong>EXC_MASK_MACH_SYSCALL</strong> +<dd> +System call with a number in the Mach call range requested. +</dl> +<p> +<dt> <var>old_exception_masks</var> +<dd> +[out array of <var>exception_mask_t</var>] +An array, each element being a mask +specifying for which exception types the corresponding element of the +other arrays apply. +<p> +<dt> <var>old_exception_count</var> +<dd> +[pointer to in/out scalar] +On input, the maximum size of the array +buffers; on output, the number of returned <exception type mask, +exception port, behavior, flavor> sets returned. +<p> +<dt> <var>old_exception_ports</var> +<dd> +[out array of exception send rights] +The returned exception ports. +<p> +<dt> <var>old_behaviors</var> +<dd> +[out array of <var>exception_behavior_t</var>] +The type of exception message to +be sent. Defined types are: +<dl> +<p> +<dt> <strong>EXCEPTION_DEFAULT</strong> +<dd> +Send a <strong>catch_exception_raise</strong> message including the thread +identity. +<p> +<dt> <strong>EXCEPTION_STATE</strong> +<dd> +Send a <strong>catch_exception_raise_state</strong> message including the +thread state. +<p> +<dt> <strong>EXCEPTION_STATE_IDENTITY</strong> +<dd> +Send a <strong>catch_exception_raise_state_identity</strong> message +including the thread identity and state. +</dl> +<p> +<dt> <var>old_flavors</var> +<dd> +[out array of <var>thread_state_flavor_t</var>] +The type of state to be sent with +the exception message. These types are defined in \*L<mach/thread_states.h>\*O. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_get_exception_ports</strong> function returns send +rights for a specified +set of exception ports belonging to <var>thread</var>. The call returns +a set of quadruples +<exception type mask, exception port, behavior, flavor> for each unique set of +<exception port, behavior, flavor> in effect for the thread where +the exception +type mask indicates for which exception types the other values apply. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_EXCEPTION_PROTECTED</strong> +<dd> +One of the requested exception ports is protected and cannot be returned. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>, +<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, +<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, +<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, +<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, +<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>. diff --git a/osfmk/man/thread_get_special_port.html b/osfmk/man/thread_get_special_port.html index 2acf05b9c..f8e0abba6 100755 --- a/osfmk/man/thread_get_special_port.html +++ b/osfmk/man/thread_get_special_port.html @@ -1 +1,76 @@ -<h2>thread_get_special_port</h2> <hr> <p> <strong>Function</strong> - Return a send right to the caller-specified special port. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_get_special_port</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>int</strong> <var>which_port</var>, <strong>thread</strong> <var>special_port</var><strong>);</strong> </pre> <h4>Macro form:</h4> <pre> <strong>kern_return_t thread_get_kernel_port</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>thread</strong> <var>special_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] The thread for which to return the port's send right. <p> <dt> <var>which_port</var> <dd> [in scalar] The special port for which the send right is requested. Valid values are: <dl> <p> <dt> <strong>THREAD_KERNEL_PORT</strong> <dd> [thread-self send right] The port used to name the thread. Used to invoke operations that affect the thread. This is the port returned by <strong>mach_thread_self</strong>. </dl> <p> <dt> <var>special_port</var> <dd> [out thread-special send right] The returned value for the port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_get_special_port</strong> function returns a send right for a special port belonging to <var>thread</var>. <p> The thread kernel port is a port for which the kernel holds the receive right. The kernel uses this port to identify the thread. <p> If one thread has a send right for the kernel port of another thread, it can use the port to perform kernel operations for the other thread. Send rights for a kernel port normally are held only by the thread to which the port belongs, or by the task that contains the thread. Using the <strong>mach_msg</strong> function, however, any thread can pass a send right for its kernel port to another thread. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>, <a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>, <a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>. \ No newline at end of file +<h2>thread_get_special_port</h2> +<hr> +<p> +<strong>Function</strong> - Return a send right to the caller-specified special port. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_get_special_port</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>int</strong> <var>which_port</var>, + <strong>thread</strong> <var>special_port</var><strong>);</strong> +</pre> + +<h4>Macro form:</h4> + +<pre> +<strong>kern_return_t thread_get_kernel_port</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>thread</strong> <var>special_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread for which to return the port's send +right. +<p> +<dt> <var>which_port</var> +<dd> +[in scalar] +The special port for which the send right is requested. Valid +values are: +<dl> +<p> +<dt> <strong>THREAD_KERNEL_PORT</strong> +<dd> +[thread-self send right] The port used to name the thread. +Used to invoke operations that affect the thread. This is the +port returned by <strong>mach_thread_self</strong>. +</dl> +<p> +<dt> <var>special_port</var> +<dd> +[out thread-special send right] +The returned value for the port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_get_special_port</strong> function returns a send +right for a special port +belonging to <var>thread</var>. +<p> +The thread kernel port is a port for which the kernel holds the +receive right. The +kernel uses this port to identify the thread. +<p> +If one thread has a send right for the kernel port of another +thread, it can use the +port to perform kernel operations for the other thread. Send +rights for a kernel +port normally are held only by the thread to which the port belongs, or by the +task that contains the thread. Using the <strong>mach_msg</strong> +function, however, any +thread can pass a send right for its kernel port to another thread. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>, +<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>, +<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>. diff --git a/osfmk/man/thread_get_state.html b/osfmk/man/thread_get_state.html index f081bbf02..7fe560ebc 100755 --- a/osfmk/man/thread_get_state.html +++ b/osfmk/man/thread_get_state.html @@ -1 +1,57 @@ -<h2>thread_get_state</h2> <hr> <p> <strong>Function</strong> - Return the execution state for a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_get_state</strong> <strong>(thread_act_t</strong> <var>target_thread</var>, <strong>thread_state_flavor_t</strong> <var>flavor</var>, <strong>thread_state_t</strong> <var>old_state</var>, <strong>mach_msg_type_number_t</strong> <var>old_state_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_thread</var> <dd> [in thread send right] The thread for which the execution state is to be returned. The calling thread cannot specify itself. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of execution state to be returned. Valid values correspond to supported machined architectures. <p> <dt> <var>old_state</var> <dd> [out structure] State information for the specified thread. <p> <dt> <var>old_state_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_get_state</strong> function returns the execution state (for example, the machine registers) for <var>target_thread</var>. flavor specifies the type of state information returned. <p> The format of the data returned is machine specific; it is defined in \*L<mach/thread_status.h>\*O. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_info.html"><strong>task_info</strong></a>, <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="thread_set_state.html"><strong>thread_set_state</strong></a>. \ No newline at end of file +<h2>thread_get_state</h2> +<hr> +<p> +<strong>Function</strong> - Return the execution state for a thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_get_state</strong> + <strong>(thread_act_t</strong> <var>target_thread</var>, + <strong>thread_state_flavor_t</strong> <var>flavor</var>, + <strong>thread_state_t</strong> <var>old_state</var>, + <strong>mach_msg_type_number_t</strong> <var>old_state_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_thread</var> +<dd> +[in thread send right] +The thread for which the execution state is to be +returned. The calling thread cannot specify itself. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of execution state to be returned. Valid values +correspond to supported machined architectures. +<p> +<dt> <var>old_state</var> +<dd> +[out structure] +State information for the specified thread. +<p> +<dt> <var>old_state_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_get_state</strong> function returns the execution +state (for example, the +machine registers) for <var>target_thread</var>. flavor specifies the type +of state information +returned. +<p> +The format of the data returned is machine specific; it is defined in +\*L<mach/thread_status.h>\*O. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="thread_set_state.html"><strong>thread_set_state</strong></a>. diff --git a/osfmk/man/thread_info.html b/osfmk/man/thread_info.html index 150b51ed3..cc3a97d1e 100755 --- a/osfmk/man/thread_info.html +++ b/osfmk/man/thread_info.html @@ -1 +1,88 @@ -<h2>thread_info</h2> <hr> <p> <strong>Function</strong> - Return information about a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_info</strong> <strong>(thread_act_t</strong> <var>target_thread</var>, <strong>thread_flavor_t</strong> <var>flavor</var>, <strong>thread_info_t</strong> <var>thread_info</var>, <strong>mach_msg_type_number_t</strong> <var>thread_info_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_thread</var> <dd> [in thread send right] The thread for which the information is to be returned. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of information to be returned. Valid values are: <dl> <p> <dt> <strong>THREAD_BASIC_INFO</strong> <dd> Returns basic information about the thread, such as the thread's run state and suspend count. The returned structure is <strong>thread_basic_info</strong>. <p> <dt> <strong>THREAD_SCHED_FIFO_INFO</strong> <dd> Returns FIFO scheduling policy information about the thread. The returned structure is <strong>policy_fifo_info</strong>. <p> <dt> <strong>THREAD_SCHED_RR_INFO</strong> <dd> Returns round-robin scheduling policy information about the thread. The returned structure is <strong>policy_rr_info</strong>. <p> <dt> <strong>THREAD_SCHED_TIMESHARE_INFO</strong> <dd> Returns timeshare scheduling policy information about the thread. The returned structure is <strong>policy_timeshare_info</strong>. </dl> <p> <dt> <var>thread_info</var> <dd> [out structure] Information about the specified thread. <p> <dt> <var>thread_info_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_info</strong> function returns an information structure of type <var>flavor</var>. <h3>NOTES</h3> <p> At any given time, a thread has only one scheduling policy in effect for it. Thus, only one of the scheduling information structures will be valid, that so indicated by the policy value returned by <strong>THREAD_BASIC_INFO</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_info.html"><strong>task_info</strong></a>, <a href="task_threads.html"><strong>task_threads</strong></a>, <a href="thread_get_state.html"><strong>thread_get_state</strong></a>, <a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>, <a href="thread_set_state.html"><strong>thread_set_state</strong></a>. <p> Data Structures: <a href="thread_basic_info.html"><strong>thread_basic_info</strong></a>, <a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>, <a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, <a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>. \ No newline at end of file +<h2>thread_info</h2> +<hr> +<p> +<strong>Function</strong> - Return information about a thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_info</strong> + <strong>(thread_act_t</strong> <var>target_thread</var>, + <strong>thread_flavor_t</strong> <var>flavor</var>, + <strong>thread_info_t</strong> <var>thread_info</var>, + <strong>mach_msg_type_number_t</strong> <var>thread_info_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_thread</var> +<dd> +[in thread send right] +The thread for which the information is to be +returned. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of information to be returned. Valid values are: +<dl> +<p> +<dt> <strong>THREAD_BASIC_INFO</strong> +<dd> +Returns basic information about the thread, such as the +thread's run state and suspend count. The returned structure is +<strong>thread_basic_info</strong>. +<p> +<dt> <strong>THREAD_SCHED_FIFO_INFO</strong> +<dd> +Returns FIFO scheduling policy information about the thread. +The returned structure is <strong>policy_fifo_info</strong>. +<p> +<dt> <strong>THREAD_SCHED_RR_INFO</strong> +<dd> +Returns round-robin scheduling policy information about the +thread. The returned structure is <strong>policy_rr_info</strong>. +<p> +<dt> <strong>THREAD_SCHED_TIMESHARE_INFO</strong> +<dd> +Returns timeshare scheduling policy information about the +thread. The returned structure is <strong>policy_timeshare_info</strong>. +</dl> +<p> +<dt> <var>thread_info</var> +<dd> +[out structure] +Information about the specified thread. +<p> +<dt> <var>thread_info_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_info</strong> function returns an information structure +of type <var>flavor</var>. +<h3>NOTES</h3> +<p> +At any given time, a thread has only one scheduling policy in +effect for it. Thus, +only one of the scheduling information structures will be valid, +that so indicated +by the policy value returned by <strong>THREAD_BASIC_INFO</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="task_threads.html"><strong>task_threads</strong></a>, +<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, +<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>, +<a href="thread_set_state.html"><strong>thread_set_state</strong></a>. +<p> +Data Structures: +<a href="thread_basic_info.html"><strong>thread_basic_info</strong></a>, +<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>, +<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, +<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>. diff --git a/osfmk/man/thread_policy.html b/osfmk/man/thread_policy.html index c8534fda9..d194eaf6a 100755 --- a/osfmk/man/thread_policy.html +++ b/osfmk/man/thread_policy.html @@ -1 +1,73 @@ -<h2>thread_policy</h2> <hr> <p> <strong>Function</strong> - Set target thread's scheduling policy state. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_policy</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>policy_t</strong> <var>policy</var>, <strong>policy_base_t</strong> <var>base</var>, <strong>base</strong> <var>base_count</var>, <strong>boolean_t</strong> <var>set_limit</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] The thread scheduling policy is to be set. <p> <dt> <var>policy</var> <dd> [in scalar] Policy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>, <strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out). <p> <dt> <var>base</var> <dd> [pointer to in structure] Base scheduling policy specific data, <strong>policy_fifo_base</strong>, <strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>. <p> <dt> <var>base_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). <p> <dt> <var>set_limit</var> <dd> [in scalar] True if the thread's scheduling limits should be restricted to allow no more service than specified by <var>base</var>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_policy</strong> function sets the scheduling policy to be applied to thread. <var>policy</var> must be a scheduling policy currently "enabled" for the thread's assigned processor set. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_POLICY</strong> <dd> The processor set to which <var>thread</var> is currently assigned does not currently enable <var>policy</var>. <p> <dt> <strong>KERN_POLICY_LIMIT</strong> <dd> The specified scheduling attributes exceeds the thread's limits. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, <a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>, <a href="task_policy.html"><strong>task_policy</strong></a>, <a href="task_set_policy.html"><strong>task_set_policy</strong></a>. <p> Data Structures: <a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, <a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, <a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. \ No newline at end of file +<h2>thread_policy</h2> +<hr> +<p> +<strong>Function</strong> - Set target thread's scheduling policy state. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_policy</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>policy_t</strong> <var>policy</var>, + <strong>policy_base_t</strong> <var>base</var>, + <strong>base</strong> <var>base_count</var>, + <strong>boolean_t</strong> <var>set_limit</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread scheduling policy is to be set. +<p> +<dt> <var>policy</var> +<dd> +[in scalar] +Policy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>, +<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out). +<p> +<dt> <var>base</var> +<dd> +[pointer to in structure] +Base scheduling policy specific data, +<strong>policy_fifo_base</strong>, <strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>. +<p> +<dt> <var>base_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +<p> +<dt> <var>set_limit</var> +<dd> +[in scalar] +True if the thread's scheduling limits should be restricted to +allow no more service than specified by <var>base</var>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_policy</strong> function sets the scheduling policy +to be applied to thread. <var>policy</var> must be a scheduling policy +currently "enabled" for the thread's assigned processor set. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_POLICY</strong> +<dd> +The processor set to which <var>thread</var> is currently assigned does +not currently enable <var>policy</var>. +<p> +<dt> <strong>KERN_POLICY_LIMIT</strong> +<dd> +The specified scheduling attributes exceeds the thread's limits. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, +<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>, +<a href="task_policy.html"><strong>task_policy</strong></a>, +<a href="task_set_policy.html"><strong>task_set_policy</strong></a>. +<p> +Data Structures: +<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, +<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, +<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. diff --git a/osfmk/man/thread_resume.html b/osfmk/man/thread_resume.html index 93d51331f..52fd856d2 100755 --- a/osfmk/man/thread_resume.html +++ b/osfmk/man/thread_resume.html @@ -1 +1,41 @@ -<h2>thread_resume</h2> <hr> <p> <strong>Function</strong> - Resume a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_resume</strong> <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_thread</var> <dd> [in thread send right] The thread to be resumed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_resume</strong> function decrements the suspend count for <var>target_thread</var> by one. The thread is resumed if its suspend count goes to zero. If the suspend count is still positive, <strong>thread_resume</strong> must be repeated until the count reaches zero. <h3>NOTES</h3> <p> An attempt to lower the suspend count below zero is ignored. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_resume.html"><strong>task_resume</strong></a>, <a href="task_suspend.html"><strong>task_suspend</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>, <a href="thread_terminate.html"><strong>thread_terminate</strong></a>. \ No newline at end of file +<h2>thread_resume</h2> +<hr> +<p> +<strong>Function</strong> - Resume a thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_resume</strong> + <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_thread</var> +<dd> +[in thread send right] +The thread to be resumed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_resume</strong> function decrements the suspend count +for <var>target_thread</var> +by one. The thread is resumed if its suspend count goes to zero. +If the suspend +count is still positive, <strong>thread_resume</strong> must be repeated +until the count reaches +zero. +<h3>NOTES</h3> +<p> +An attempt to lower the suspend count below zero is ignored. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_resume.html"><strong>task_resume</strong></a>, +<a href="task_suspend.html"><strong>task_suspend</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>, +<a href="thread_terminate.html"><strong>thread_terminate</strong></a>. diff --git a/osfmk/man/thread_sample.html b/osfmk/man/thread_sample.html index 2e2eae6be..3cbcf30ad 100755 --- a/osfmk/man/thread_sample.html +++ b/osfmk/man/thread_sample.html @@ -1 +1,43 @@ -<h2>thread_sample</h2> <hr> <p> <strong>Function</strong> - Perform periodic PC sampling for a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_sample</strong> <strong>(thread_act_t</strong> <var>sample_thread</var>, <strong>mach_port_make_send_t</strong> <var>reply_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>sample_thread</var> <dd> [in thread send right] Thread whose PC is to be sampled <p> <dt> <var>reply_port</var> <dd> [in sample receive (to be converted to send) right] Port to which PC sample buffers are sent. A value of <strong>MACH_PORT_NULL</strong> stops PC sampling for the thread. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_sample</strong> function causes the program counter (PC) of the specified <var>sample_thread</var> to be sampled periodically (whenever the thread happens to be running at the time of the kernel's "hardclock" interrupt). The set of PC sample values obtained are saved in buffers which are sent to the specified <var>reply_port</var> in <strong>receive_samples</strong> messages. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_sample.html"><strong>task_sample</strong></a>, <a href="receive_samples.html"><strong>receive_samples</strong></a>. \ No newline at end of file +<h2>thread_sample</h2> +<hr> +<p> +<strong>Function</strong> - Perform periodic PC sampling for a thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_sample</strong> + <strong>(thread_act_t</strong> <var>sample_thread</var>, + <strong>mach_port_make_send_t</strong> <var>reply_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>sample_thread</var> +<dd> +[in thread send right] +Thread whose PC is to be sampled +<p> +<dt> <var>reply_port</var> +<dd> +[in sample receive (to be converted to send) right] +Port to which PC +sample buffers are sent. A value of <strong>MACH_PORT_NULL</strong> stops PC +sampling for the thread. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_sample</strong> function causes the program counter +(PC) of the specified +<var>sample_thread</var> to be sampled periodically (whenever the thread happens to be +running at the time of the kernel's "hardclock" interrupt). +The set of PC sample +values obtained are saved in buffers which are sent to the specified +<var>reply_port</var> in +<strong>receive_samples</strong> messages. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_sample.html"><strong>task_sample</strong></a>, +<a href="receive_samples.html"><strong>receive_samples</strong></a>. diff --git a/osfmk/man/thread_set_exception_ports.html b/osfmk/man/thread_set_exception_ports.html index 39bc5a5a1..069edb279 100755 --- a/osfmk/man/thread_set_exception_ports.html +++ b/osfmk/man/thread_set_exception_ports.html @@ -1 +1,143 @@ -<h2>thread_set_exception_ports</h2> <hr> <p> <strong>Function</strong> - Set exception ports for a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_set_exception_ports</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>exception_mask_t</strong> <var>exception_types</var>, <strong>mach_port_t</strong> <var>exception_port</var>, <strong>exception_behavior_t</strong> <var>behavior</var>, <strong>thread_state_flavor_t</strong> <var>flavor</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] The thread for which to set the ports. <p> <dt> <var>exception_types</var> <dd> [in scalar] A flag word indicating the types of exceptions for which the exception port applies: <dl> <p> <dt> <strong>EXC_MASK_BAD_ACCESS</strong> <dd> Could not access memory. <p> <dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> <dd> Instruction failed. Illegal or undefined instruction or operand. <p> <dt> <strong>EXC_MASK_ARITHMETIC</strong> <dd> Arithmetic exception. <p> <dt> <strong>EXC_MASK_EMULATION</strong> <dd> Emulation instruction. Emulation support instruction encountered. <p> <dt> <strong>EXC_MASK_SOFTWARE</strong> <dd> Software generated exception. <p> <dt> <strong>EXC_MASK_BREAKPOINT</strong> <dd> Trace, breakpoint, etc. <p> <dt> <strong>EXC_MASK_SYSCALL</strong> <dd> System call requested. <p> <dt> <strong>EXC_MASK_MACH_SYSCALL</strong> <dd> System call with a number in the Mach call range requested. </dl> <p> <dt> <var>exception_port</var> <dd> [in exception send right] The exception port for all selected exception types. <p> <dt> <var>behavior</var> <dd> [in scalar] The type of exception message to be sent. Defined types are: <dl> <p> <dt> <strong>EXCEPTION_DEFAULT</strong> <dd> Send a <strong>catch_exception_raise</strong> message including the thread identity. <p> <dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong> <dd> Send a <strong>catch_exception_raise</strong> message including the thread identity. Mark the exception port (and associated exceptions) as protected. <p> <dt> <strong>EXCEPTION_STATE</strong> <dd> Send a <strong>catch_exception_raise_state</strong> message including the thread state. <p> <dt> <strong>EXCEPTION_STATE_PROTECTED</strong> <dd> Send a <strong>catch_exception_raise_state</strong> message including the thread state. Mark the exception port (and associated exceptions) as protected. <p> <dt> <strong>EXCEPTION_STATE_IDENTITY</strong> <dd> Send a <strong>catch_exception_raise_state_identity</strong> message including the thread identity and state. <p> <dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong> <dd> Send a <strong>catch_exception_raise_state_identity</strong> message including the thread identity and state. Mark the exception port (and associated exceptions) as protected. </dl> <p> <dt> <var>flavor</var> <dd> [in scalar] The type of state to be sent with the exception message. These types are defined in \*L<mach/thread_states.h>\*O. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_set_exception_ports</strong> function sets a specified set of exception ports belonging to <var>thread</var>. <h3>NOTES</h3> <p> If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is the host name port, Mach kernel traps are executed by the kernel as expected; any other value causes the attempted execution of these system call numbers to be considered an exception. <p> A "protected" exception port is one which cannot be fetched and for which exception processing cannot be aborted (<strong>thread_abort</strong>). <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>, <a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, <a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, <a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, <a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>, <a href="thread_abort.html"><strong>thread_abort</strong></a>. \ No newline at end of file +<h2>thread_set_exception_ports</h2> +<hr> +<p> +<strong>Function</strong> - Set exception ports for a thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_set_exception_ports</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>exception_mask_t</strong> <var>exception_types</var>, + <strong>mach_port_t</strong> <var>exception_port</var>, + <strong>exception_behavior_t</strong> <var>behavior</var>, + <strong>thread_state_flavor_t</strong> <var>flavor</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread for which to set the ports. +<p> +<dt> <var>exception_types</var> +<dd> +[in scalar] +A flag word indicating the types of exceptions for which the +exception port applies: +<dl> +<p> +<dt> <strong>EXC_MASK_BAD_ACCESS</strong> +<dd> +Could not access memory. +<p> +<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong> +<dd> +Instruction failed. Illegal or undefined instruction or operand. +<p> +<dt> <strong>EXC_MASK_ARITHMETIC</strong> +<dd> +Arithmetic exception. +<p> +<dt> <strong>EXC_MASK_EMULATION</strong> +<dd> +Emulation instruction. Emulation support instruction +encountered. +<p> +<dt> <strong>EXC_MASK_SOFTWARE</strong> +<dd> +Software generated exception. +<p> +<dt> <strong>EXC_MASK_BREAKPOINT</strong> +<dd> +Trace, breakpoint, etc. +<p> +<dt> <strong>EXC_MASK_SYSCALL</strong> +<dd> +System call requested. +<p> +<dt> <strong>EXC_MASK_MACH_SYSCALL</strong> +<dd> +System call with a number in the Mach call range requested. +</dl> +<p> +<dt> <var>exception_port</var> +<dd> +[in exception send right] +The exception port for all selected exception +types. +<p> +<dt> <var>behavior</var> +<dd> +[in scalar] +The type of exception message to be sent. Defined types are: +<dl> +<p> +<dt> <strong>EXCEPTION_DEFAULT</strong> +<dd> +Send a <strong>catch_exception_raise</strong> message including the thread +identity. +<p> +<dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong> +<dd> +Send a <strong>catch_exception_raise</strong> message including the thread +identity. Mark the exception port (and associated exceptions) +as protected. +<p> +<dt> <strong>EXCEPTION_STATE</strong> +<dd> +Send a <strong>catch_exception_raise_state</strong> message including the +thread state. +<p> +<dt> <strong>EXCEPTION_STATE_PROTECTED</strong> +<dd> +Send a <strong>catch_exception_raise_state</strong> message including the +thread state. Mark the exception port (and associated +exceptions) as protected. +<p> +<dt> <strong>EXCEPTION_STATE_IDENTITY</strong> +<dd> +Send a <strong>catch_exception_raise_state_identity</strong> message +including the thread identity and state. +<p> +<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong> +<dd> +Send a <strong>catch_exception_raise_state_identity</strong> message +including the thread identity and state. Mark the exception port +(and associated exceptions) as protected. +</dl> +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of state to be sent with the exception message. +These types are defined in \*L<mach/thread_states.h>\*O. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_set_exception_ports</strong> function sets a specified +set of exception +ports belonging to <var>thread</var>. +<h3>NOTES</h3> +<p> +If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is +the host name port, Mach kernel traps are executed by the kernel as expected; +any other value causes the attempted execution of these system call numbers to +be considered an exception. +<p> +A "protected" exception port is one which cannot be fetched and for which +exception processing cannot be aborted (<strong>thread_abort</strong>). +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>, +<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, +<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, +<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, +<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, +<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>, +<a href="thread_abort.html"><strong>thread_abort</strong></a>. diff --git a/osfmk/man/thread_set_policy.html b/osfmk/man/thread_set_policy.html index ea36db885..5bdc54d44 100755 --- a/osfmk/man/thread_set_policy.html +++ b/osfmk/man/thread_set_policy.html @@ -1 +1,82 @@ -<h2>thread_set_policy</h2> <hr> <p> <strong>Function</strong> - Set target thread's scheduling policy state. (Protected Interface.) <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_set_policy</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>processor_set_t</strong> <var>processor_set</var>, <strong>policy_t</strong> <var>policy</var>, <strong>policy_base_t</strong> <var>base</var>, <strong>mach_msg_type_number_t</strong> <var>base_count</var>, <strong>policy_limit_t</strong> <var>limit</var>, <strong>mach_msg_type_number_</strong> <var>limit_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] The thread scheduling policy is to be set. <p> <dt> <var>processor_set</var> <dd> [in processor-set-control send right] The control port for the processor set to which the thread is currently assigned. <p> <dt> <var>policy</var> <dd> [in scalar] Policy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>, <strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out). <p> <dt> <var>base</var> <dd> [pointer to in structure] Base policy specific data, <strong>policy_fifo_base</strong>, <strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>. <p> <dt> <var>base_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). <p> <dt> <var>limit</var> <dd> [pointer to in structure] Policy specific limits, <strong>policy_fifo_limit</strong>, <strong>policy_rr_limit</strong> or <strong>policy_timeshare_limit</strong>. <p> <dt> <var>limit_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_set_policy</strong> function sets the scheduling attributes, both base and limit, for <var>thread</var>. <var>policy</var> may be any policy implemented by the processor set whether or not it is enabled. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_PROCESSOR_SET</strong> <dd> <var>processor_set</var> is not the thread's processor set control port. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, <a href="thread_policy.html"><strong>thread_policy</strong></a>, <a href="task_policy.html"><strong>task_policy</strong></a>, <a href="task_set_policy.html"><strong>task_set_policy</strong></a>. <p> Data Structures: <a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, <a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, <a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. \ No newline at end of file +<h2>thread_set_policy</h2> +<hr> +<p> +<strong>Function</strong> - Set target thread's scheduling policy state. (Protected Interface.) +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_set_policy</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>processor_set_t</strong> <var>processor_set</var>, + <strong>policy_t</strong> <var>policy</var>, + <strong>policy_base_t</strong> <var>base</var>, + <strong>mach_msg_type_number_t</strong> <var>base_count</var>, + <strong>policy_limit_t</strong> <var>limit</var>, + <strong>mach_msg_type_number_</strong> <var>limit_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread scheduling policy is to be set. +<p> +<dt> <var>processor_set</var> +<dd> +[in processor-set-control send right] +The control port for the processor +set to which the thread is currently assigned. +<p> +<dt> <var>policy</var> +<dd> +[in scalar] +Policy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>, +<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out). +<p> +<dt> <var>base</var> +<dd> +[pointer to in structure] +Base policy specific data, <strong>policy_fifo_base</strong>, +<strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>. +<p> +<dt> <var>base_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +<p> +<dt> <var>limit</var> +<dd> +[pointer to in structure] +Policy specific limits, <strong>policy_fifo_limit</strong>, +<strong>policy_rr_limit</strong> or <strong>policy_timeshare_limit</strong>. +<p> +<dt> <var>limit_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_set_policy</strong> function sets the scheduling +attributes, both base and limit, for <var>thread</var>. +<var>policy</var> may be any policy implemented by the processor set +whether or not it is enabled. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_PROCESSOR_SET</strong> +<dd> +<var>processor_set</var> is not the thread's processor set control port. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>, +<a href="thread_policy.html"><strong>thread_policy</strong></a>, +<a href="task_policy.html"><strong>task_policy</strong></a>, +<a href="task_set_policy.html"><strong>task_set_policy</strong></a>. +<p> +Data Structures: +<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>, +<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>, +<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>. diff --git a/osfmk/man/thread_set_special_port.html b/osfmk/man/thread_set_special_port.html index 5359a6fae..251d27536 100755 --- a/osfmk/man/thread_set_special_port.html +++ b/osfmk/man/thread_set_special_port.html @@ -1 +1,59 @@ -<h2>thread_set_special_port</h2> <hr> <p> <strong>Function</strong> - Set caller-specified special port belonging to the target thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_set_special_port</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>int</strong> <var>which_port</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> </pre> <h4>Macro form:</h4> <pre> <strong>kern_return_t thread_set_kernel_port</strong> <strong>(thread_act_t</strong> <var>thread</var>, <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>thread</var> <dd> [in thread send right] The thread for which to set the port. <p> <dt> <var>which_port</var> <dd> [in scalar] The special port to be set. Valid values are: <dl> <p> <dt> <strong>THREAD_KERNEL_PORT</strong> <dd> [thread-self port] The thread's kernel port. Used by the kernel to receive messages from the thread. This is the port returned by <strong>mach_thread_self</strong>. </dl> <p> <dt> <var>special_port</var> <dd> [in thread-special send right] The value for the port. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_set_special_port</strong> function sets a special port belonging to <var>thread</var>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>, <a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>, <a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>. \ No newline at end of file +<h2>thread_set_special_port</h2> +<hr> +<p> +<strong>Function</strong> - Set caller-specified special port belonging to the target thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_set_special_port</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>int</strong> <var>which_port</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> +</pre> + +<h4>Macro form:</h4> +<pre> +<strong>kern_return_t thread_set_kernel_port</strong> + <strong>(thread_act_t</strong> <var>thread</var>, + <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread for which to set the port. +<p> +<dt> <var>which_port</var> +<dd> +[in scalar] +The special port to be set. Valid values are: +<dl> +<p> +<dt> <strong>THREAD_KERNEL_PORT</strong> +<dd> +[thread-self port] The thread's kernel port. Used by the kernel +to receive messages from the thread. This is the port returned +by <strong>mach_thread_self</strong>. +</dl> +<p> +<dt> <var>special_port</var> +<dd> +[in thread-special send right] +The value for the port. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_set_special_port</strong> function sets a special +port belonging to <var>thread</var>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>, +<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>, +<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>. diff --git a/osfmk/man/thread_set_state.html b/osfmk/man/thread_set_state.html index 3e64d6ca9..db4172aeb 100755 --- a/osfmk/man/thread_set_state.html +++ b/osfmk/man/thread_set_state.html @@ -1 +1,55 @@ -<h2>thread_set_state</h2> <hr> <p> <strong>Function</strong> - Set the target thread's user-mode execution state. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_set_state</strong> <strong>(thread_act_t</strong> <var>target_thread</var>, <strong>thread_state_flavor_t</strong> <var>flavor</var>, <strong>thread_state_t</strong> <var>new_state</var>, <strong>target_thread</strong> <var>new_state_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_thread</var> <dd> [in thread send right] The thread for which to set the execution state. The calling thread cannot specify itself. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of state to set. Valid values correspond to supported machine architecture features. <p> <dt> <var>new_state</var> <dd> [pointer to in structure] State information for the specified thread. <p> <dt> <var>new_state_count</var> <dd> [in scalar] The size of the buffer (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_set_state</strong> function sets the execution state (for example, the machine registers) for <var>target_thread</var>. <var>flavor</var> specifies the type of state to set. <p> The format of the state to set is machine specific; it is defined in <strong>mach/thread_status.h</strong>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_info.html"><strong>task_info</strong></a>, <a href="thread_get_state.html"><strong>thread_get_state</strong></a>, <a href="thread_info.html"><strong>thread_info</strong></a>. \ No newline at end of file +<h2>thread_set_state</h2> +<hr> +<p> +<strong>Function</strong> - Set the target thread's user-mode execution state. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_set_state</strong> + <strong>(thread_act_t</strong> <var>target_thread</var>, + <strong>thread_state_flavor_t</strong> <var>flavor</var>, + <strong>thread_state_t</strong> <var>new_state</var>, + <strong>target_thread</strong> <var>new_state_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_thread</var> +<dd> +[in thread send right] +The thread for which to set the execution state. +The calling thread cannot specify itself. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of state to set. Valid values correspond to +supported machine architecture features. +<p> +<dt> <var>new_state</var> +<dd> +[pointer to in structure] +State information for the specified thread. +<p> +<dt> <var>new_state_count</var> +<dd> +[in scalar] +The size of the buffer (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_set_state</strong> function sets the execution state +(for example, the +machine registers) for <var>target_thread</var>. <var>flavor</var> specifies the type +of state to set. +<p> +The format of the state to set is machine specific; it is defined in +<strong>mach/thread_status.h</strong>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, +<a href="thread_info.html"><strong>thread_info</strong></a>. diff --git a/osfmk/man/thread_suspend.html b/osfmk/man/thread_suspend.html index 78c2dba35..72af9ba5c 100755 --- a/osfmk/man/thread_suspend.html +++ b/osfmk/man/thread_suspend.html @@ -1 +1,57 @@ -<h2>thread_suspend</h2> <hr> <p> <strong>Function</strong> - Suspend a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_suspend</strong> <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_thread</var> <dd> [in thread send right] The thread to be suspended. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_suspend</strong> function increments the suspend count for <var>target_thread</var> and prevents the thread from executing any more user-level instructions. <p> In this context, a user-level instruction can be either a machine instruction executed in user mode or a system trap instruction, including a page fault. If a thread is currently executing within a system trap, the kernel code may continue to execute until it reaches the system return code or it may suspend within the kernel code. In either case, the system trap returns when the thread resumes. <p> To resume a suspended thread, use <strong>thread_resume</strong>. If the suspend count is greater than one, <strong>thread_resume</strong> must be repeated that number of times. <h3>CAUTIONS</h3> <p> Unpredictable results may occur if a program suspends a thread and alters its user state so that its direction is changed upon resuming. Note that the <strong>thread_abort</strong> function allows a system call to be aborted only if it is progressing in a predictable way. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_resume.html"><strong>task_resume</strong></a>, <a href="task_suspend.html"><strong>task_suspend</strong></a>, <a href="thread_abort.html"><strong>thread_abort</strong></a>, <a href="thread_get_state.html"><strong>thread_get_state</strong></a>, <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="thread_resume.html"><strong>thread_resume</strong></a>, <a href="thread_set_state.html"><strong>thread_set_state</strong></a>, <a href="thread_terminate.html"><strong>thread_terminate</strong></a>. \ No newline at end of file +<h2>thread_suspend</h2> +<hr> +<p> +<strong>Function</strong> - Suspend a thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_suspend</strong> + <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_thread</var> +<dd> +[in thread send right] +The thread to be suspended. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_suspend</strong> function increments the suspend +count for <var>target_thread</var> +and prevents the thread from executing any more user-level instructions. +<p> +In this context, a user-level instruction can be either a machine instruction +executed in user mode or a system trap instruction, including +a page fault. If a +thread is currently executing within a system trap, the kernel +code may continue +to execute until it reaches the system return code or it may +suspend within the +kernel code. In either case, the system trap returns when the thread resumes. +<p> +To resume a suspended thread, use <strong>thread_resume</strong>. If +the suspend count is +greater than one, <strong>thread_resume</strong> must be repeated that +number of times. +<h3>CAUTIONS</h3> +<p> +Unpredictable results may occur if a program suspends a thread and alters its +user state so that its direction is changed upon resuming. Note that the +<strong>thread_abort</strong> function allows a system call to be aborted +only if it is progressing in a +predictable way. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_resume.html"><strong>task_resume</strong></a>, +<a href="task_suspend.html"><strong>task_suspend</strong></a>, +<a href="thread_abort.html"><strong>thread_abort</strong></a>, +<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, +<a href="thread_info.html"><strong>thread_info</strong></a>, +<a href="thread_resume.html"><strong>thread_resume</strong></a>, +<a href="thread_set_state.html"><strong>thread_set_state</strong></a>, +<a href="thread_terminate.html"><strong>thread_terminate</strong></a>. diff --git a/osfmk/man/thread_switch.html b/osfmk/man/thread_switch.html index 8e4d67ffa..25f6b5508 100755 --- a/osfmk/man/thread_switch.html +++ b/osfmk/man/thread_switch.html @@ -1 +1,124 @@ -<h2>thread_switch</h2> <hr> <p> <strong>Function</strong> - Cause context switch with options. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_switch</strong> <strong>(mach_port_t</strong> <var>new_thread</var>, <strong>int</strong> <var>option</var>, <strong>mach_msg_timeout_t</strong> <var>time</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>new_thread</var> <dd> [in thread send right] Thread to which the processor should switch context. <p> <dt> <var>option</var> <dd> [in scalar] Options applicable to the context switch. <p> <dt> <var>time</var> <dd> [in scalar] Time duration during which the thread should be affected by <var>option</var>. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_switch</strong> function provides low-level access to the scheduler's context switching code. <var>new_thread</var> is a hint that implements hand-off scheduling. The operating system will attempt to switch directly to the new thread (bypassing the normal logic that selects the next thread to run) if possible. Since this is a hint, it may be incorrect; it is ignored if it doesn't specify a thread on the same host as the current thread or if the scheduler cannot switch to that thread (i.e., not runable or already running on another processor). In this case, the normal logic to select the next thread to run is used; the current thread may continue running if there is no other appropriate thread to run. <p> The <var>option</var> argument specifies the interpretation and use of <var>time</var>. The possible values (from \*L<mach/thread_switch.h>\*O) are: <dl> <dt> <strong>SWITCH_OPTION_NONE</strong> <dd> The <var>time</var> argument is ignored. <dt> <strong>SWITCH_OPTION_WAIT</strong> <dd> The thread is blocked for the specified <var>time</var>. This wait cannot be canceled by <strong>thread_resume</strong>; only <strong>thread_abort</strong> can terminate this wait. <dt> <strong>SWITCH_OPTION_DEPRESS</strong> <dd> The thread's scheduling attributes are temporarily set so as to provide it with the lowest possible service for duration <var>time</var>. The scheduling depression is aborted when <var>time</var> has passed, when the current thread is next run (either via hand-off scheduling or because the processor set has nothing better to do), or when <strong>thread_abort</strong> or <strong>thread_depress_abort</strong> is applied to the current thread. Changing the thread's scheduling attributes (via <strong>thread_policy</strong>) will not affect this depression. <dt> <strong>SWITCH_OPTION_IDLE</strong> <dd> This option is similar to <strong>SWITCH_OPTION_DEPRESS</strong> however, the thread's scheduling attributes are temporarily set so as to place it at a service level that is below all runnable threads for duration <var>time</var>. The scheduling depression is aborted when <var>time</var> has passed, when the current thread is next run (either via hand-off scheduling or because the processor set has nothing better to do), or when <strong>thread_abort</strong> or <strong>thread_depress_abort</strong> is applied to the current thread. Changing the thread's scheduling attributes (via <strong>thread_policy</strong>) will not affect this depression. </dl> <p> The minimum time and units of time can be obtained as the <var>min_timeout</var> value from the <strong>HOST_SCHED_INFO</strong> flavor of <strong>host_info</strong>. <h3>NOTES</h3> <p> <strong>thread_switch</strong> is often called when the current thread can proceed no further for some reason; the various options and arguments allow information about this reason to be transmitted to the kernel. The <var>new_thread</var> argument (hand-off scheduling) is useful when the identity of the thread that must make progress before the current thread runs again is known. The <strong>SWITCH_OPTION_WAIT</strong> option is used when the amount of time that the current thread must wait before it can do anything useful can be estimated and is fairly short, especially when the identity of the thread for which this thread must wait is not known. <h3>CAUTIONS</h3> <p> Users should beware of calling <strong>thread_switch</strong> with an invalid hint (e.g., <strong>THREAD_NULL</strong>) and no option. Because the time-sharing scheduler varies the priority of threads based on usage, this may result in a waste of CPU time if the thread that must be run is of lower priority. The use of the <strong>SWITCH_OPTION_DEPRESS</strong> option in this situation is highly recommended. <p> <strong>thread_switch</strong> ignores policies. Users relying on the preemption semantics of a fixed time policy should be aware that <strong>thread_switch</strong> ignores these semantics; it will run the specified <var>new_thread</var> independent of its scheduling attributes and those of any threads that could run instead. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_abort.html"><strong>thread_abort</strong></a>, <a href="thread_depress_abort.html"><strong>thread_depress_abort</strong></a>. \ No newline at end of file +<h2>thread_switch</h2> +<hr> +<p> +<strong>Function</strong> - Cause context switch with options. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_switch</strong> + <strong>(mach_port_t</strong> <var>new_thread</var>, + <strong>int</strong> <var>option</var>, + <strong>mach_msg_timeout_t</strong> <var>time</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>new_thread</var> +<dd> +[in thread send right] +Thread to which the processor should switch +context. +<p> +<dt> <var>option</var> +<dd> +[in scalar] +Options applicable to the context switch. +<p> +<dt> <var>time</var> +<dd> +[in scalar] +Time duration during which the thread should be affected by +<var>option</var>. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_switch</strong> function provides low-level access +to the scheduler's +context switching code. <var>new_thread</var> is a hint that implements +hand-off scheduling. +The operating system will attempt to switch directly to the new thread +(bypassing the normal logic that selects the next thread to run) +if possible. Since this is a hint, it may be incorrect; it is ignored if it +doesn't specify a thread on the same host as the current thread or if +the scheduler cannot switch to that thread (i.e., +not runable or already running on another processor). In this +case, the normal +logic to select the next thread to run is used; the current thread +may continue +running if there is no other appropriate thread to run. +<p> +The <var>option</var> argument specifies the interpretation and use of <var>time</var>. +The possible values (from \*L<mach/thread_switch.h>\*O) are: +<dl> +<dt> <strong>SWITCH_OPTION_NONE</strong> +<dd> +The <var>time</var> argument is ignored. +<dt> <strong>SWITCH_OPTION_WAIT</strong> +<dd> +The thread is blocked for the specified <var>time</var>. This wait cannot be +canceled by <strong>thread_resume</strong>; +only <strong>thread_abort</strong> can terminate this wait. +<dt> <strong>SWITCH_OPTION_DEPRESS</strong> +<dd> +The thread's scheduling attributes are temporarily set so as to provide +it with the lowest possible service for duration <var>time</var>. The scheduling +depression is aborted when <var>time</var> has passed, when the current thread is +next run (either via hand-off scheduling or because the processor set +has nothing better to do), or when <strong>thread_abort</strong> or +<strong>thread_depress_abort</strong> is applied to the current thread. +Changing the thread's scheduling attributes (via <strong>thread_policy</strong>) +will not affect this depression. +<dt> <strong>SWITCH_OPTION_IDLE</strong> +<dd> +This option is similar to <strong>SWITCH_OPTION_DEPRESS</strong> however, the +thread's scheduling attributes are temporarily set so as to place it +at a service level that is below all runnable threads for +duration <var>time</var>. The scheduling depression is aborted +when <var>time</var> has passed, when the current thread is +next run (either via hand-off scheduling or because the processor set +has nothing better to do), or when <strong>thread_abort</strong> or +<strong>thread_depress_abort</strong> is applied to the current thread. +Changing the thread's scheduling attributes (via <strong>thread_policy</strong>) +will not affect this depression. +</dl> +<p> +The minimum time and units of time can be obtained as the <var>min_timeout</var> +value from the <strong>HOST_SCHED_INFO</strong> flavor of <strong>host_info</strong>. +<h3>NOTES</h3> +<p> +<strong>thread_switch</strong> is often called when the current thread +can proceed no further +for some reason; the various options and arguments allow information about +this reason to be transmitted to the kernel. The <var>new_thread</var> +argument (hand-off +scheduling) is useful when the identity of the thread that must make progress +before the current thread runs again is known. The <strong>SWITCH_OPTION_WAIT</strong> +option is used when the amount of time that the current thread +must wait before it +can do anything useful can be estimated and is fairly short, +especially when the +identity of the thread for which this thread must wait is not known. +<h3>CAUTIONS</h3> +<p> +Users should beware of calling <strong>thread_switch</strong> with an +invalid hint (e.g., <strong>THREAD_NULL</strong>) and no option. +Because the time-sharing scheduler varies the +priority of threads based on usage, this may result in a waste +of CPU time if the +thread that must be run is of lower priority. The use of the +<strong>SWITCH_OPTION_DEPRESS</strong> option in this situation is highly recommended. +<p> +<strong>thread_switch</strong> ignores policies. Users relying on the +preemption semantics of a +fixed time policy should be aware that <strong>thread_switch</strong> +ignores these semantics; +it will run the specified <var>new_thread</var> independent of its scheduling +attributes and +those of any threads that could run instead. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_abort.html"><strong>thread_abort</strong></a>, +<a href="thread_depress_abort.html"><strong>thread_depress_abort</strong></a>. diff --git a/osfmk/man/thread_terminate.html b/osfmk/man/thread_terminate.html index 6852997e0..0149ec360 100755 --- a/osfmk/man/thread_terminate.html +++ b/osfmk/man/thread_terminate.html @@ -1 +1,31 @@ -<h2>thread_terminate</h2> <hr> <p> <strong>Function</strong> - Destroy a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_terminate</strong> <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_thread</var> <dd> [in thread send right] The thread to be destroyed. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_terminate</strong> function kills <var>target_thread</var>. <h3>RETURN VALUES</h3> <p> Only generic errors apply. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_terminate.html"><strong>task_terminate</strong></a>, <a href="task_threads.html"><strong>task_threads</strong></a>, <a href="thread_create.html"><strong>thread_create</strong></a>, <a href="thread_resume.html"><strong>thread_resume</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>. \ No newline at end of file +<h2>thread_terminate</h2> +<hr> +<p> +<strong>Function</strong> - Destroy a thread. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_terminate</strong> + <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_thread</var> +<dd> +[in thread send right] +The thread to be destroyed. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_terminate</strong> function kills <var>target_thread</var>. +<h3>RETURN VALUES</h3> +<p> +Only generic errors apply. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_terminate.html"><strong>task_terminate</strong></a>, +<a href="task_threads.html"><strong>task_threads</strong></a>, +<a href="thread_create.html"><strong>thread_create</strong></a>, +<a href="thread_resume.html"><strong>thread_resume</strong></a>, +<a href="thread_suspend.html"><strong>thread_suspend</strong></a>. diff --git a/osfmk/man/thread_wire.html b/osfmk/man/thread_wire.html index f52f7a984..740aaaf09 100755 --- a/osfmk/man/thread_wire.html +++ b/osfmk/man/thread_wire.html @@ -1 +1,53 @@ -<h2>thread_wire</h2> <hr> <p> <strong>Function</strong> - Mark the thread as privileged with respect to kernel resources. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_wire</strong> <strong>(host_priv_t</strong> <var>host_priv</var>, <strong>thread_act_t</strong> <var>thread</var>, <strong>boolean_t</strong> <var>wired</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host_priv</var> <dd> [in host-control send right] The privileged control port for the host on which the thread executes. <p> <dt> <var>thread</var> <dd> [in thread send right] The thread to be wired. <p> <dt> <var>wired</var> <dd> [in scalar] <strong>TRUE</strong> if the thread is to be wired. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_wire</strong> function marks the thread as "wired". A "wired" thread is always eligible to be scheduled and can consume physical memory even when free memory is scarce. This property should be assigned to threads in the default page-out path. Threads not in the default page-out path should not have this property to prevent the kernel's free list of pages from being exhausted. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ARGUMENT</strong> <dd> <var>thread</var> is not a thread port. .P <var>host_priv</var> is not the control port for the host on which <var>thread</var> executes. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_wire.html"><strong>vm_wire</strong></a>. \ No newline at end of file +<h2>thread_wire</h2> +<hr> +<p> +<strong>Function</strong> - Mark the thread as privileged with respect to kernel resources. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t thread_wire</strong> + <strong>(host_priv_t</strong> <var>host_priv</var>, + <strong>thread_act_t</strong> <var>thread</var>, + <strong>boolean_t</strong> <var>wired</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host_priv</var> +<dd> +[in host-control send right] +The privileged control port for the host on +which the thread executes. +<p> +<dt> <var>thread</var> +<dd> +[in thread send right] +The thread to be wired. +<p> +<dt> <var>wired</var> +<dd> +[in scalar] +<strong>TRUE</strong> if the thread is to be wired. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>thread_wire</strong> function marks the thread as "wired". +A "wired" thread is +always eligible to be scheduled and can consume physical memory even when +free memory is scarce. This property should be assigned to threads in the +default page-out path. Threads not in the default page-out path +should not have +this property to prevent the kernel's free list of pages from being exhausted. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ARGUMENT</strong> +<dd> +<var>thread</var> is not a thread port. +.P +<var>host_priv</var> is not the control port for the host on which <var>thread</var> +executes. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_wire.html"><strong>vm_wire</strong></a>. diff --git a/osfmk/man/tvalspec.html b/osfmk/man/tvalspec.html index cdb56a439..5374a7526 100755 --- a/osfmk/man/tvalspec.html +++ b/osfmk/man/tvalspec.html @@ -1 +1,44 @@ -<h2>tvalspec</h2> <hr> <p> <strong>Structure</strong> - Defines format of system time values. <h3>SYNOPSIS</h3> <pre> <strong>struct tvalspec</strong> <strong>{</strong> <strong>unsigned int</strong> <var>tv_sec</var><strong>;</strong> <strong>clock_res_t</strong> <var>tv_nsec</var><strong>;</strong> <strong>};</strong> <strong>typedef struct tvalspec tvalspec_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>tv_sec</var> <dd> Seconds. <p> <dt> <var>tv_nsec</var> <dd> Nanoseconds. </dl> <h3>DESCRIPTION</h3> <p> The <strong>tvalspec</strong> structure defines the format of the time structure supplied to or returned from the kernel. This definition conforms to the Posix 1003.4 <var>timespec</var> definition where the <var>tv_nsec</var> structure member is valid if (0 =< <var>tv_nsec</var> < 109) and the time period described is ((<var>tv_sec</var> * 109) + <var>tv_nsec</var>) nanoseconds. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="clock_get_time.html"><strong>clock_get_time</strong></a>, <a href="clock_set_time.html"><strong>clock_set_time</strong></a>, <a href="clock_sleep.html"><strong>clock_sleep</strong></a>, <a href="clock_alarm.html"><strong>clock_alarm</strong></a>, <a href="clock_alarm_reply.html"><strong>clock_alarm_reply</strong></a>. <p> Data Structures: <a href="mapped_tvalspec.html"><strong>mapped_tvalspec</strong></a>. \ No newline at end of file +<h2>tvalspec</h2> +<hr> +<p> +<strong>Structure</strong> - Defines format of system time values. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct tvalspec</strong> +<strong>{</strong> + <strong>unsigned int</strong> <var>tv_sec</var><strong>;</strong> + <strong>clock_res_t</strong> <var>tv_nsec</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct tvalspec tvalspec_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>tv_sec</var> +<dd> +Seconds. +<p> +<dt> <var>tv_nsec</var> +<dd> +Nanoseconds. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>tvalspec</strong> structure defines the format of the time +structure supplied to or +returned from the kernel. This definition conforms to the Posix +1003.4 <var>timespec</var> +definition where the <var>tv_nsec</var> structure member is valid +if (0 =< <var>tv_nsec</var> < 109) and +the time period described is ((<var>tv_sec</var> * 109) + <var>tv_nsec</var>) nanoseconds. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="clock_get_time.html"><strong>clock_get_time</strong></a>, +<a href="clock_set_time.html"><strong>clock_set_time</strong></a>, +<a href="clock_sleep.html"><strong>clock_sleep</strong></a>, +<a href="clock_alarm.html"><strong>clock_alarm</strong></a>, +<a href="clock_alarm_reply.html"><strong>clock_alarm_reply</strong></a>. +<p> +Data Structures: +<a href="mapped_tvalspec.html"><strong>mapped_tvalspec</strong></a>. diff --git a/osfmk/man/vm_allocate.html b/osfmk/man/vm_allocate.html index dacfe2fd7..53de44045 100755 --- a/osfmk/man/vm_allocate.html +++ b/osfmk/man/vm_allocate.html @@ -1 +1,106 @@ -<h2>vm_allocate</h2> <hr> <p> <strong>Function</strong> - Allocate a region of virtual memory. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_allocate</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>boolean_t</strong> <var>anywhere</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task in whose address space the region is to be allocated. <p> <dt> <var>address</var> <dd> [pointer to in/out scalar] The starting address for the region. If the region as specified by the given starting address and size would not lie within the task's un-allocated memory, the kernel does not allocate the region. If allocated, the kernel returns the starting address actually used for the allocated region. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes to allocate. <p> <dt> <var>anywhere</var> <dd> [in scalar] Placement indicator. The valid values are: <dl> <p> <dt> <strong>TRUE</strong> <dd> The kernel allocates the region in the next unused space that is sufficient within the address space. The kernel returns the starting address actually used in <var>address</var>. <p> <dt> <strong>FALSE</strong> <dd> The kernel allocates the region starting at <var>address</var> unless that space is already allocated. </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_allocate</strong> function allocates a region of virtual memory in the specified task's address space. A new region is always zero filled. <p> If <var>anywhere</var> is <strong>TRUE</strong>, the returned <var>address</var> will be at a page boundary; otherwise, the region starts at the beginning of the virtual page containing <var>address</var>. <var>size</var> is always rounded up to an integral number of pages. Because of this rounding to virtual page boundaries, the amount of memory allocated may be greater than <var>size</var>. Use <strong>host_page_size</strong> to find the current virtual page size. <p> Initially, there are no access restrictions on any of the pages of the newly allocated region. Child tasks inherit the new region as a copy. <h3>NOTES</h3> <p> To establish different protections or inheritance for the new region, use the <strong>vm_protect</strong> and <strong>vm_inherit</strong> functions. <p> A task's address space can contain both explicitly allocated memory and automatically allocated memory. The <strong>vm_allocate</strong> function explicitly allocates memory. The kernel automatically allocates memory to hold out-of-line data passed in a message (and received with <strong>mach_msg</strong>). The kernel allocates memory for the passed data as an integral number of pages. <p> This interface is machine word length dependent because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> The specified address is illegal or reserved. <p> <dt> <strong>KERN_NO_SPACE</strong> <dd> There is not enough space in the task's address space to allocate the new region. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, <a href="vm_inherit.html"><strong>vm_inherit</strong></a>, <a href="vm_protect.html"><strong>vm_protect</strong></a>, <a href="vm_region.html"><strong>vm_region</strong></a>, <a href="host_page_size.html"><strong>host_page_size</strong></a>. \ No newline at end of file +<h2>vm_allocate</h2> +<hr> +<p> +<strong>Function</strong> - Allocate a region of virtual memory. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_allocate</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>boolean_t</strong> <var>anywhere</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task in whose address space the +region is to be allocated. +<p> +<dt> <var>address</var> +<dd> +[pointer to in/out scalar] +The starting address for the region. If the +region as specified by the given starting address and size would not lie +within the task's un-allocated memory, the kernel does not allocate the +region. If allocated, the kernel returns the starting address actually used +for the allocated region. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes to allocate. +<p> +<dt> <var>anywhere</var> +<dd> +[in scalar] +Placement indicator. The valid values are: +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The kernel allocates the region in the next unused space that +is sufficient within the address space. The kernel returns the +starting address actually used in <var>address</var>. +<p> +<dt> <strong>FALSE</strong> +<dd> +The kernel allocates the region starting at <var>address</var> unless that +space is already allocated. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_allocate</strong> function allocates a region of virtual +memory in the specified +task's address space. A new region is always zero filled. +<p> +If <var>anywhere</var> is <strong>TRUE</strong>, the returned +<var>address</var> will be at +a page boundary; otherwise, the region starts at the beginning +of the virtual page +containing <var>address</var>. +<var>size</var> is always rounded up to an integral number of pages. +Because of this rounding to virtual page boundaries, the amount of memory +allocated may be greater than <var>size</var>. Use <strong>host_page_size</strong> to find +the current virtual page size. +<p> +Initially, there are no access restrictions on any of the pages of the newly +allocated region. Child tasks inherit the new region as a copy. +<h3>NOTES</h3> +<p> +To establish different protections or inheritance for the new region, use the +<strong>vm_protect</strong> and <strong>vm_inherit</strong> functions. +<p> +A task's address space can contain both explicitly allocated memory and +automatically allocated memory. The <strong>vm_allocate</strong> function +explicitly allocates +memory. The kernel automatically allocates memory to hold out-of-line data +passed in a message (and received with <strong>mach_msg</strong>). The kernel allocates +memory for the passed data as an integral number of pages. +<p> +This interface is machine word length dependent because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +The specified address is illegal or reserved. +<p> +<dt> <strong>KERN_NO_SPACE</strong> +<dd> +There is not enough space in the task's address space to allocate the +new region. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, +<a href="vm_inherit.html"><strong>vm_inherit</strong></a>, +<a href="vm_protect.html"><strong>vm_protect</strong></a>, +<a href="vm_region.html"><strong>vm_region</strong></a>, +<a href="host_page_size.html"><strong>host_page_size</strong></a>. + diff --git a/osfmk/man/vm_behavior_set.html b/osfmk/man/vm_behavior_set.html index 77087b889..d51fbfae3 100755 --- a/osfmk/man/vm_behavior_set.html +++ b/osfmk/man/vm_behavior_set.html @@ -1 +1,88 @@ -<h2>vm_behavior_set</h2> <hr> <p> <strong>Function</strong> - Specify expected access patterns for the target VM region. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_behavior_set</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>vm_behavior_t</strong> <var>behavior</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task in whose address space the memory object behavior is to be set. <p> <dt> <var>address</var> <dd> [in scalar] The starting address for the memory region. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes in the region. <p> <dt> <var>behavior</var> <dd> [in scalar] The expected reference pattern for the memory. Possible values are: <dl> <p> <dt> <strong>VM_BEHAVIOR_DEFAULT</strong> <dd> The system's default behavior. Assumes strong locality of reference, so LRU page replacement, possibly with pre-fetch, would be appropriate. <p> <dt> <strong>VM_BEHAVIOR_RANDOM</strong> <dd> No particular order expected. Assumes weak locality of reference, so LRU page replacement may be ineffective. <p> <dt> <strong>VM_BEHAVIOR_SEQUENTIAL</strong> <dd> Forward sequential order. <p> <dt> <strong>VM_BEHAVIOR_RSEQNTL</strong> <dd> Reverse sequential order. </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_behavior_set</strong> function informs the kernel of the expected access pattern for a region of memory. The kernel uses this information to bias its prefetch and page replacement algorithms. <p> The region starts at the beginning of the virtual page containing <var>address</var>; it ends at the end of the virtual page containing <var>address</var> + <var>size</var> - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than <var>size</var>. Use <strong>host_page_size</strong> to find the current virtual page size. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> The specified address is illegal or reserved. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_region.html"><strong>vm_region</strong></a>, <a href="host_page_size.html"><strong>host_page_size</strong></a>. \ No newline at end of file +<h2>vm_behavior_set</h2> +<hr> +<p> +<strong>Function</strong> - Specify expected access patterns for the target VM region. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_behavior_set</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>vm_behavior_t</strong> <var>behavior</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task in whose address space the +memory object behavior is to be set. +<p> +<dt> <var>address</var> +<dd> +[in scalar] +The starting address for the memory region. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes in the region. +<p> +<dt> <var>behavior</var> +<dd> +[in scalar] +The expected reference pattern for the memory. Possible +values are: +<dl> +<p> +<dt> <strong>VM_BEHAVIOR_DEFAULT</strong> +<dd> +The system's default behavior. Assumes strong locality of +reference, so LRU page replacement, possibly with pre-fetch, +would be appropriate. +<p> +<dt> <strong>VM_BEHAVIOR_RANDOM</strong> +<dd> +No particular order expected. Assumes weak locality of +reference, so LRU page replacement may be ineffective. +<p> +<dt> <strong>VM_BEHAVIOR_SEQUENTIAL</strong> +<dd> +Forward sequential order. +<p> +<dt> <strong>VM_BEHAVIOR_RSEQNTL</strong> +<dd> +Reverse sequential order. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_behavior_set</strong> function informs the kernel of +the expected access +pattern for a region of memory. The kernel uses this information +to bias its prefetch and page +replacement algorithms. +<p> +The region starts at the beginning of the virtual page containing +<var>address</var>; it ends at the end of the virtual page containing +<var>address</var> + <var>size</var> - 1. Because of this +rounding to virtual page boundaries, the amount of memory affected may be +greater than <var>size</var>. Use <strong>host_page_size</strong> +to find the current virtual page size. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +The specified address is illegal or reserved. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_region.html"><strong>vm_region</strong></a>, +<a href="host_page_size.html"><strong>host_page_size</strong></a>. diff --git a/osfmk/man/vm_copy.html b/osfmk/man/vm_copy.html index 21f579bed..ea4c926f1 100755 --- a/osfmk/man/vm_copy.html +++ b/osfmk/man/vm_copy.html @@ -1 +1,72 @@ -<h2>vm_copy</h2> <hr> <p> <strong>Function</strong> - Copy a region of virtual memory. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_copy</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>source_address</var>, <strong>vm_size_t</strong> <var>count</var>, <strong>vm_address_t</strong> <var>dest_address</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task whose memory is to be copied. <p> <dt> <var>source_address</var> <dd> [in scalar] The starting address for the source region. The address must be on a page boundary. <p> <dt> <var>count</var> <dd> [in scalar] The number of bytes in the source region. The number of bytes must convert to an integral number of virtual pages. <p> <dt> <var>dest_address</var> <dd> [in scalar] The starting address for the destination region. The address must be on a page boundary. </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_copy</strong> function copies a source region to a destination region within the same task's virtual memory. It is semantically equivalent to <strong>vm_read</strong> followed by <strong>vm_write</strong>. The destination region can overlap the source region. <p> The destination region must already be allocated. The source region must be readable, and the destination region must be writable. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_PROTECTION_FAILURE</strong> <dd> The source region is protected against reading, or the destination region is protected against writing. <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> An address is illegal or specifies a non-allocated region, or there is not enough memory following one of the addresses. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_protect.html"><strong>vm_protect</strong></a>, <a href="vm_read.html"><strong>vm_read</strong></a>, <a href="vm_write.html"><strong>vm_write</strong></a>, <a href="host_page_size.html"><strong>host_page_size</strong></a>. \ No newline at end of file +<h2>vm_copy</h2> +<hr> +<p> +<strong>Function</strong> - Copy a region of virtual memory. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_copy</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>source_address</var>, + <strong>vm_size_t</strong> <var>count</var>, + <strong>vm_address_t</strong> <var>dest_address</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task whose memory is to be copied. +<p> +<dt> <var>source_address</var> +<dd> +[in scalar] +The starting address for the source region. The address must +be on a page boundary. +<p> +<dt> <var>count</var> +<dd> +[in scalar] +The number of bytes in the source region. The number of +bytes must convert to an integral number of virtual pages. +<p> +<dt> <var>dest_address</var> +<dd> +[in scalar] +The starting address for the destination region. The address +must be on a page boundary. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_copy</strong> function copies a source region to a destination +region within the +same task's virtual memory. It is semantically equivalent to +<strong>vm_read</strong> followed +by <strong>vm_write</strong>. The destination region can overlap the source region. +<p> +The destination region must already be allocated. The source region must be +readable, and the destination region must be writable. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_PROTECTION_FAILURE</strong> +<dd> +The source region is protected against reading, or the destination +region is protected against writing. +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +An address is illegal or specifies a non-allocated region, or there is not +enough memory following one of the addresses. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_protect.html"><strong>vm_protect</strong></a>, +<a href="vm_read.html"><strong>vm_read</strong></a>, +<a href="vm_write.html"><strong>vm_write</strong></a>, +<a href="host_page_size.html"><strong>host_page_size</strong></a>. diff --git a/osfmk/man/vm_deallocate.html b/osfmk/man/vm_deallocate.html index f7e6c3f2a..894c8f93b 100755 --- a/osfmk/man/vm_deallocate.html +++ b/osfmk/man/vm_deallocate.html @@ -1 +1,67 @@ -<h2>vm_deallocate</h2> <hr> <p> <strong>Function</strong> - Deallocate a region of virtual memory. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_deallocate</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task in whose address space the region is to be deallocated. <p> <dt> <var>address</var> <dd> [in scalar] The starting address for the region. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes to deallocate. </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_deallocate</strong> function deallocates a region of virtual memory in the specified task's address space. The region starts at the beginning of the virtual page containing <var>address</var> and ends at the end of the virtual page containing <var>address</var> + <var>size</var> - 1. Because of this rounding to virtual page boundaries, the amount of memory deallocated may be greater than <var>size</var>. Use <strong>host_page_size</strong> to find the current virtual page size. <p> <strong>vm_deallocate</strong> affects only <var>target_task</var>. Other tasks that have access to the deallocated memory can continue to reference it. <h3>NOTES</h3> <p> <strong>vm_deallocate</strong> can be used to deallocate memory passed as out-of-line data in a message. <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> The address is illegal or specifies a non-allocated region. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="vm_allocate.html"><strong>vm_allocate</strong></a>, <a href="vm_map.html"><strong>vm_map</strong></a>, <a href="host_page_size.html"><strong>host_page_size</strong></a>. \ No newline at end of file +<h2>vm_deallocate</h2> +<hr> +<p> +<strong>Function</strong> - Deallocate a region of virtual memory. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_deallocate</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task in whose address space the +region is to be deallocated. +<p> +<dt> <var>address</var> +<dd> +[in scalar] +The starting address for the region. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes to deallocate. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_deallocate</strong> function deallocates a region of +virtual memory in the +specified task's address space. +The region starts at the beginning of the virtual page containing +<var>address</var> and ends +at the end of the virtual page containing <var>address</var> ++ <var>size</var> - 1. Because of this +rounding to virtual page boundaries, the amount of memory deallocated may be +greater than <var>size</var>. Use <strong>host_page_size</strong> +to find the current virtual page size. +<p> +<strong>vm_deallocate</strong> affects only <var>target_task</var>. Other tasks +that have access to the deallocated memory can continue to reference it. +<h3>NOTES</h3> +<p> +<strong>vm_deallocate</strong> can be used to deallocate memory passed +as out-of-line data in a +message. +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +The address is illegal or specifies a non-allocated region. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="mach_msg.html"><strong>mach_msg</strong></a>, +<a href="vm_allocate.html"><strong>vm_allocate</strong></a>, +<a href="vm_map.html"><strong>vm_map</strong></a>, +<a href="host_page_size.html"><strong>host_page_size</strong></a>. diff --git a/osfmk/man/vm_inherit.html b/osfmk/man/vm_inherit.html index a7546e0e6..e748f054e 100755 --- a/osfmk/man/vm_inherit.html +++ b/osfmk/man/vm_inherit.html @@ -1 +1,95 @@ -<h2>vm_inherit</h2> <hr> <p> <strong>Function</strong> - Set a VM region's inheritance attribute. <p> <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_inherit</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>vm_inherit_t</strong> <var>new_inheritance</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task whose address space contains the region. <p> <dt> <var>address</var> <dd> [in scalar] The starting address for the region. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes in the region. <p> <dt> <var>new_inheritance</var> <dd> [in scalar] The new inheritance attribute for the region. Valid values are: <dl> <p> <dt> <strong>VM_INHERIT_SHARE</strong> <dd> Allows child tasks to share the region. <p> <dt> <strong>VM_INHERIT_COPY</strong> <dd> Gives child tasks a copy of the region. <p> <dt> <strong>VM_INHERIT_NONE</strong> <dd> Provides no access to the region for child tasks. </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_inherit</strong> function sets the inheritance attribute for a region within the specified task's address space. The inheritance attribute determines the type of access established for child tasks at task creation. <p> Because inheritance applies to virtual pages, the specified <var>address</var> and <var>size</var> are rounded to page boundaries, as follows: the region starts at the beginning of the virtual page containing <var>address</var>; it ends at the end of the virtual page containing <var>address</var> + <var>size</var> - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than <var>size</var>. Use <strong>host_page_size</strong> to find the current virtual page size. <p> A parent and a child task can share the same physical memory only if the inheritance for the memory is set to <strong>VM_INHERIT_SHARE</strong> before the child task is created. Other than through the use of an external memory manager (see <strong>vm_map</strong>), this is the only way that two tasks can share memory. <p> Note that all the threads within a task share the task's memory. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> The address is illegal or specifies a non-allocated region. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_create.html"><strong>task_create</strong></a>, <a href="vm_map.html"><strong>vm_map</strong></a>, <a href="vm_region.html"><strong>vm_region</strong></a>, <a href="norma_task_clone.html"><strong>norma_task_create</strong></a>. \ No newline at end of file +<h2>vm_inherit</h2> +<hr> +<p> +<strong>Function</strong> - Set a VM region's inheritance attribute. +<p> +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_inherit</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>vm_inherit_t</strong> <var>new_inheritance</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task whose address space contains +the region. +<p> +<dt> <var>address</var> +<dd> +[in scalar] +The starting address for the region. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes in the region. +<p> +<dt> <var>new_inheritance</var> +<dd> +[in scalar] +The new inheritance attribute for the region. Valid values are: +<dl> +<p> +<dt> <strong>VM_INHERIT_SHARE</strong> +<dd> +Allows child tasks to share the region. +<p> +<dt> <strong>VM_INHERIT_COPY</strong> +<dd> +Gives child tasks a copy of the region. +<p> +<dt> <strong>VM_INHERIT_NONE</strong> +<dd> +Provides no access to the region for child tasks. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_inherit</strong> function sets the inheritance attribute +for a region within the +specified task's address space. The inheritance attribute determines +the type of +access established for child tasks at task creation. +<p> +Because inheritance applies to virtual pages, the specified <var>address</var> +and <var>size</var> are +rounded to page boundaries, as follows: the region starts at +the beginning of the +virtual page containing <var>address</var>; it ends at the end of the virtual +page containing +<var>address</var> + <var>size</var> - 1. +Because of this rounding to virtual page boundaries, the +amount of memory affected may be greater than <var>size</var>. Use +<strong>host_page_size</strong> to find the current virtual page size. +<p> +A parent and a child task can share the same physical memory only if the +inheritance for the memory is set to <strong>VM_INHERIT_SHARE</strong> before +the child task is +created. Other than through the use of an external memory manager (see +<strong>vm_map</strong>), this is the only way that two tasks can share memory. +<p> +Note that all the threads within a task share the task's memory. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +The address is illegal or specifies a non-allocated region. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_create.html"><strong>task_create</strong></a>, +<a href="vm_map.html"><strong>vm_map</strong></a>, +<a href="vm_region.html"><strong>vm_region</strong></a>, +<a href="norma_task_clone.html"><strong>norma_task_create</strong></a>. diff --git a/osfmk/man/vm_machine_attribute.html b/osfmk/man/vm_machine_attribute.html index d12ff4331..601af32f5 100755 --- a/osfmk/man/vm_machine_attribute.html +++ b/osfmk/man/vm_machine_attribute.html @@ -1 +1,112 @@ -<h2>vm_machine_attribute</h2> <hr> <p> <strong>Function</strong> - Get/set the target memory region's special attributes. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_machine_attribute</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>vm_machine_attribute_t</strong> <var>attribute</var>, <strong>vm_machine_attribute_val_t</strong> <var>value</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task in whose address space the memory object is to be manipulated. <p> <dt> <var>address</var> <dd> [in scalar] The starting address for the memory region. The granularity of rounding of this value to page boundaries is implementation dependent. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes in the region. The granularity of rounding of this value to page boundaries is implementation dependent. <p> <dt> <var>attribute</var> <dd> [in scalar] The name of the attribute to be get/set. Possible values are: <dl> <p> <dt> <strong>MATTR_CACHE</strong> <dd> Cachability. Aside from the generic values listed below, the following special values are defined: <dl> <p> <dt> <strong>MATTR_VAL_CACHE_FLUSH</strong> <dd> Flush from all caches <p> <dt> <strong>MATTR_VAL_DCACHE_FLUSH</strong> <dd> Flush from data caches <p> <dt> <strong>MATTR_VAL_ICACHE_FLUSH</strong> <dd> Flush from instruction caches </dl> <p> <dt> <strong>MATTR_MIGRATE</strong> <dd> Migratability. <p> <dt> <strong>MATTR_REPLICATE</strong> <dd> Replicability. </dl> <p> <dt> <var>value</var> <dd> [pointer to in/out scalar] The new value for the attribute. The old value is also returned in this variable. The new value can be a specific value listed above, or one of the following generic values: <dl> <p> <dt> <strong>MATTR_VAL_OFF</strong> <dd> Turn attribute off. <p> <dt> <strong>MATTR_VAL_ON</strong> <dd> Turn attribute on. <p> <dt> <strong>MATTR_VAL_GET</strong> <dd> No change, just return current value. </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_machine_attribute</strong> function gets and sets special attributes of the memory region implemented by the underlying <strong>pmap</strong> module. These attributes are properties such as cachability, migratability and replicability. The behavior of this function is machine dependent. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> The address is illegal or specifies a non-allocated region. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_wire.html"><strong>vm_wire</strong></a>. \ No newline at end of file +<h2>vm_machine_attribute</h2> +<hr> +<p> +<strong>Function</strong> - Get/set the target memory region's special attributes. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_machine_attribute</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>vm_machine_attribute_t</strong> <var>attribute</var>, + <strong>vm_machine_attribute_val_t</strong> <var>value</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task in whose address space the +memory object is to be manipulated. +<p> +<dt> <var>address</var> +<dd> +[in scalar] +The starting address for the memory region. The granularity +of rounding of this value to page boundaries is implementation +dependent. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes in the region. The granularity of +rounding of this value to page boundaries is implementation dependent. +<p> +<dt> <var>attribute</var> +<dd> +[in scalar] +The name of the attribute to be get/set. Possible values are: +<dl> +<p> +<dt> <strong>MATTR_CACHE</strong> +<dd> +Cachability. Aside from the generic values listed below, the +following special values are defined: +<dl> +<p> +<dt> <strong>MATTR_VAL_CACHE_FLUSH</strong> +<dd> +Flush from all caches +<p> +<dt> <strong>MATTR_VAL_DCACHE_FLUSH</strong> +<dd> +Flush from data caches +<p> +<dt> <strong>MATTR_VAL_ICACHE_FLUSH</strong> +<dd> +Flush from instruction caches +</dl> +<p> +<dt> <strong>MATTR_MIGRATE</strong> +<dd> +Migratability. +<p> +<dt> <strong>MATTR_REPLICATE</strong> +<dd> +Replicability. +</dl> +<p> +<dt> <var>value</var> +<dd> +[pointer to in/out scalar] +The new value for the attribute. The old value +is also returned in this variable. The new value can be a specific value +listed above, or one of the following generic values: +<dl> +<p> +<dt> <strong>MATTR_VAL_OFF</strong> +<dd> +Turn attribute off. +<p> +<dt> <strong>MATTR_VAL_ON</strong> +<dd> +Turn attribute on. +<p> +<dt> <strong>MATTR_VAL_GET</strong> +<dd> +No change, just return current value. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_machine_attribute</strong> function gets and sets special +attributes of the +memory region implemented by the underlying <strong>pmap</strong> module. These attributes +are properties such as cachability, migratability and replicability. +The behavior of this function is machine dependent. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +The address is illegal or specifies a non-allocated region. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_wire.html"><strong>vm_wire</strong></a>. diff --git a/osfmk/man/vm_map.html b/osfmk/man/vm_map.html index ce59762cd..3ae9ea697 100755 --- a/osfmk/man/vm_map.html +++ b/osfmk/man/vm_map.html @@ -1 +1,225 @@ -<h2>vm_map</h2> <hr> <p> <strong>Function</strong> - Map the specified memory object to a region of virtual memory. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_map</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>vm_address_t</strong> <var>mask</var>, <strong>boolean_t</strong> <var>anywhere</var>, <strong>memory_object_t</strong> <var>memory_object</var>, <strong>vm_offset_t</strong> <var>offset</var>, <strong>boolean_t</strong> <var>copy</var>, <strong>vm_prot_t</strong> <var>cur_protection</var>, <strong>vm_prot_t</strong> <var>max_protection</var>, <strong>vm_inherit_t</strong> <var>inheritance</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task in whose address space the memory object is to be mapped. <p> <dt> <var>address</var> <dd> [pointer to in/out scalar] The starting address for the mapped object. The mapped object will start at the beginning of the page containing <var>address</var>. If there is not enough room following the address, the kernel does not map the object. The kernel returns the starting address actually used for the mapped object. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes to allocate for the object. The kernel rounds this number up to an integral number of virtual pages. <p> <dt> <var>mask</var> <dd> [in scalar] Alignment restrictions for starting address. Bits turned on in the mask will not be turned on in the starting address. <p> <dt> <var>anywhere</var> <dd> [in scalar] Placement indicator. The valid values are: <dl> <p> <dt> <strong>TRUE</strong> <dd> The kernel allocates the region in the next unused space that is sufficient within the address space. The kernel returns the starting address actually used in <var>address</var>. <p> <dt> <strong>FALSE</strong> <dd> The kernel allocates the region starting at <var>address</var> unless that space is already allocated. </dl> <p> <dt> <var>memory_object</var> <dd> [in memory-object send right] The port naming the memory object. If <strong>MEMORY_OBJECT_NULL</strong> is specified, the kernel allocates zero-filled memory, as with <strong>vm_allocate</strong>. <p> <dt> <var>offset</var> <dd> [in scalar] An offset within the memory object, in bytes. The kernel maps <var>address</var> to the specified offset. <p> <dt> <var>copy</var> <dd> [in scalar] Copy indicator. If true, the kernel copies the region of the memory object to the specified task's address space. If false, the region is directly mapped. <p> <dt> <var>cur_protection</var> <dd> [in scalar] The initial current protection for the region. Valid values are obtained by or'ing together the following values: <dl> <p> <dt> <strong>VM_PROT_READ</strong> <dd> Allows read access. <p> <dt> <strong>VM_PROT_WRITE</strong> <dd> Allows write access. <p> <dt> <strong>VM_PROT_EXECUTE</strong> <dd> Allows execute access. </dl> <p> <dt> <var>max_protection</var> <dd> [in scalar] The maximum protection for the region. Values are the same as for <var>cur_protection</var>. <p> <dt> <var>inheritance</var> <dd> [in scalar] The initial inheritance attribute for the region. Valid values are: <dl> <p> <dt> <strong>VM_INHERIT_SHARE</strong> <dd> Allows child tasks to share the region. <p> <dt> <strong>VM_INHERIT_COPY</strong> <dd> Gives child tasks a copy of the region. <p> <dt> <strong>VM_INHERIT_NONE</strong> <dd> Provides no access to the region for child tasks. </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_map</strong> function maps a portion of the specified memory object into the virtual address space belonging to <var>target_task</var>. The target task can be the calling task or another task, identified by its task kernel port. <p> The portion of the memory object mapped is determined by <var>offset</var> and <var>size</var>. The kernel maps <var>address</var> to the offset, so that an access to the memory starts at the offset in the object. <p> The <var>mask</var> parameter specifies additional alignment restrictions on the kernel's selection of the starting address. Uses for this mask include: <ul> <li> Forcing the memory address alignment for a mapping to be the same as the alignment within the memory object. <li> Quickly finding the beginning of an allocated region by performing bit arithmetic on an address known to be in the region. <li> Emulating a larger virtual page size. </ul> <p> The <var>cur_protection</var>, <var>max_protection</var>, and <var>inheritance</var> parameters set the protection and inheritance attributes for the mapped object. As a rule, at least the maximum protection should be specified so that a server can make a restricted (for example, read-only) mapping in a client atomically. The current protection and inheritance parameters are provided for convenience so that the caller does not have to call <strong>vm_inherit</strong> and <strong>vm_protect</strong> separately. <p> The same memory object can be mapped more than once and by more than one task. If an object is mapped by multiple tasks, the kernel maintains consistency for all the mappings if they use the same page alignment for <var>offset</var> and are on the same host. In this case, the virtual memory to which the object is mapped is shared by all the tasks. Changes made by one task in its address space are visible to all the other tasks. The call will not return until the memory object is ready for use. <h3>NOTES</h3> <p> <strong>vm_map</strong> allocates a region in a task's address space and maps the specified memory object to this region. <strong>vm_allocate</strong> allocates a zero-filled temporary region in a task's address space. <p> Before a memory object can be mapped, a port naming it must be acquired from the memory manager serving it. <p> This interface is machine word length specific because of the virtual address parameter. <h3>CAUTIONS</h3> <p> Do not attempt to map a memory object unless it has been provided by a memory manager that implements the memory object interface. If another type of port is specified, a thread that accesses the mapped virtual memory may become permanently hung or may receive a memory exception. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_NO_SPACE</strong> <dd> There is not enough space in the task's address space to allocate the new region for the memory object. <p> <dt> <strong>KERN_PROTECTION_FAILURE</strong> <dd> <var>max_protection</var> or <var>cur_protection</var> exceeds that permitted by <var>memory_object</var>. <p> <dt> <strong>KERN_INVALID_OBJECT</strong> <dd> The memory manager failed to map the memory object. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_allocate.html"><strong>vm_allocate</strong></a>, <a href="vm_remap.html"><strong>vm_remap</strong></a>. \ No newline at end of file +<h2>vm_map</h2> +<hr> +<p> +<strong>Function</strong> - Map the specified memory object to a region of virtual memory. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_map</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>vm_address_t</strong> <var>mask</var>, + <strong>boolean_t</strong> <var>anywhere</var>, + <strong>memory_object_t</strong> <var>memory_object</var>, + <strong>vm_offset_t</strong> <var>offset</var>, + <strong>boolean_t</strong> <var>copy</var>, + <strong>vm_prot_t</strong> <var>cur_protection</var>, + <strong>vm_prot_t</strong> <var>max_protection</var>, + <strong>vm_inherit_t</strong> <var>inheritance</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task in whose address space the +memory object is to be mapped. +<p> +<dt> <var>address</var> +<dd> +[pointer to in/out scalar] +The starting address for the mapped object. +The mapped object will start at the beginning of the page containing +<var>address</var>. If there is not enough room following the address, the kernel +does not map the object. The kernel returns the starting address +actually used for the mapped object. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes to allocate for the object. The kernel +rounds this number up to an integral number of virtual pages. +<p> +<dt> <var>mask</var> +<dd> +[in scalar] +Alignment restrictions for starting address. Bits turned on in +the mask will not be turned on in the starting address. +<p> +<dt> <var>anywhere</var> +<dd> +[in scalar] +Placement indicator. The valid values are: +<dl> +<p> +<dt> <strong>TRUE</strong> +<dd> +The kernel allocates the region in the next unused space that +is sufficient within the address space. The kernel returns the +starting address actually used in <var>address</var>. +<p> +<dt> <strong>FALSE</strong> +<dd> +The kernel allocates the region starting at <var>address</var> unless that +space is already allocated. +</dl> +<p> +<dt> <var>memory_object</var> +<dd> +[in memory-object send right] +The port naming the +memory object. If <strong>MEMORY_OBJECT_NULL</strong> is +specified, the kernel allocates zero-filled memory, as with <strong>vm_allocate</strong>. +<p> +<dt> <var>offset</var> +<dd> +[in scalar] +An offset within the memory object, in bytes. The kernel +maps <var>address</var> to the specified offset. +<p> +<dt> <var>copy</var> +<dd> +[in scalar] +Copy indicator. If true, the kernel copies the region of the +memory object to the specified task's address space. If false, the region +is directly mapped. +<p> +<dt> <var>cur_protection</var> +<dd> +[in scalar] +The initial current protection for the region. Valid values are +obtained by or'ing together the following values: +<dl> +<p> +<dt> <strong>VM_PROT_READ</strong> +<dd> +Allows read access. +<p> +<dt> <strong>VM_PROT_WRITE</strong> +<dd> +Allows write access. +<p> +<dt> <strong>VM_PROT_EXECUTE</strong> +<dd> +Allows execute access. +</dl> +<p> +<dt> <var>max_protection</var> +<dd> +[in scalar] +The maximum protection for the region. Values are the same +as for <var>cur_protection</var>. +<p> +<dt> <var>inheritance</var> +<dd> +[in scalar] +The initial inheritance attribute for the region. Valid values +are: +<dl> +<p> +<dt> <strong>VM_INHERIT_SHARE</strong> +<dd> +Allows child tasks to share the region. +<p> +<dt> <strong>VM_INHERIT_COPY</strong> +<dd> +Gives child tasks a copy of the region. +<p> +<dt> <strong>VM_INHERIT_NONE</strong> +<dd> +Provides no access to the region for child tasks. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_map</strong> function maps a portion of the specified +memory object into the +virtual address space belonging to <var>target_task</var>. The target task +can be the calling +task or another task, identified by its task kernel port. +<p> +The portion of the memory object mapped is determined by <var>offset</var> +and <var>size</var>. The +kernel maps <var>address</var> to the offset, so that an access to the memory +starts at the offset in the object. +<p> +The <var>mask</var> parameter specifies additional alignment restrictions on +the kernel's selection of the starting address. Uses for this mask include: +<ul> +<li> +Forcing the memory address alignment for a mapping to be the same as the +alignment within the memory object. +<li> +Quickly finding the beginning of an allocated region by performing bit +arithmetic on an address known to be in the region. +<li> +Emulating a larger virtual page size. +</ul> +<p> +The <var>cur_protection</var>, <var>max_protection</var>, and <var>inheritance</var> +parameters set the +protection and inheritance attributes for the mapped object. +As a rule, at least the +maximum protection should be specified so that a server can make +a restricted (for +example, read-only) mapping in a client atomically. The current +protection and +inheritance parameters are provided for convenience so that the +caller does not +have to call <strong>vm_inherit</strong> and <strong>vm_protect</strong> separately. +<p> +The same memory object can be mapped more than once and by more than one +task. If an object is mapped by multiple tasks, the kernel maintains +consistency +for all the mappings if they use the same page alignment for <var>offset</var> +and are on +the same host. In this case, the virtual memory to which the +object is mapped is +shared by all the tasks. Changes made by one task in its address space are +visible to all the other tasks. +The call will not return until the +memory object is ready for +use. +<h3>NOTES</h3> +<p> +<strong>vm_map</strong> allocates a region in a task's address space +and maps the specified +memory object to this region. <strong>vm_allocate</strong> allocates +a zero-filled temporary +region in a task's address space. +<p> +Before a memory object can be mapped, a port naming it must be acquired from +the memory manager serving it. +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>CAUTIONS</h3> +<p> +Do not attempt to map a memory object unless it has been provided by a +memory manager that implements the memory object interface. +If another type of port +is specified, a thread that accesses the mapped virtual memory may become +permanently hung or may receive a memory exception. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_NO_SPACE</strong> +<dd> +There is not enough space in the task's address space to allocate the +new region for the memory object. +<p> +<dt> <strong>KERN_PROTECTION_FAILURE</strong> +<dd> +<var>max_protection</var> or <var>cur_protection</var> exceeds +that permitted by <var>memory_object</var>. +<p> +<dt> <strong>KERN_INVALID_OBJECT</strong> +<dd> +The memory manager failed to map the memory object. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_allocate.html"><strong>vm_allocate</strong></a>, +<a href="vm_remap.html"><strong>vm_remap</strong></a>. diff --git a/osfmk/man/vm_msync.html b/osfmk/man/vm_msync.html index e3d0fd6d1..eff768e2d 100755 --- a/osfmk/man/vm_msync.html +++ b/osfmk/man/vm_msync.html @@ -1 +1,83 @@ -<h2>vm_msync</h2> <hr> <p> <strong>Function</strong> - Synchronize the specified region of virtual memory. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_msync</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>target_task</strong> <var>sync_flags</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task whose address space contains the region. <p> <dt> <var>address</var> <dd> [in scalar] The starting address for the region. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes in the region. <p> <dt> <var>sync_flags</var> <dd> [in scalar] The bit-wise <strong>OR</strong> of flags affecting the synchronization. Specifying both <strong>VM_SYNC_SYNCHRONOUS</strong> and <strong>VM_SYNC_ASYNCHRONOUS</strong> is invalid. <dl> <p> <dt> <strong>VM_SYNC_INVALIDATE</strong> <dd> Flushes pages in the range. Only precious pages are returned to the memory manager unless either <strong>VM_SYNC_SYNCHRONOUS</strong> or <strong>VM_SYNC_ASYNCHRONOUS</strong> is also set. <p> <dt> <strong>VM_SYNC_SYNCHRONOUS</strong> <dd> Writes dirty and precious pages back to the memory manager, waits for pages to reach backing storage. <p> <dt> <strong>VM_SYNC_ASYNCHRONOUS</strong> <dd> Writes dirty and precious pages back to the memory manager, returns without waiting for pages to reach backing storage. </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_msync</strong> function synchronizes the contents of a memory range with its backing store image by flushing or cleaning the contents of the specified range to the range's memory manager, engaging in a synchronization protocol with the manager (<strong>memory_object_synchronize</strong>). The client does not return from this call until the memory manager responds (to the kernel) with <strong>memory_object_synchronize_completed</strong>. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> The address is illegal or specifies a non-allocated region. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>, <a href="MO_SY_completed.html"><strong>memory_object_synchronize_completed</strong></a>. \ No newline at end of file +<h2>vm_msync</h2> +<hr> +<p> +<strong>Function</strong> - Synchronize the specified region of virtual memory. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_msync</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>target_task</strong> <var>sync_flags</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task whose address space contains +the region. +<p> +<dt> <var>address</var> +<dd> +[in scalar] +The starting address for the region. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes in the region. +<p> +<dt> <var>sync_flags</var> +<dd> +[in scalar] +The bit-wise <strong>OR</strong> of flags affecting the synchronization. +Specifying both <strong>VM_SYNC_SYNCHRONOUS</strong> and +<strong>VM_SYNC_ASYNCHRONOUS</strong> is invalid. +<dl> +<p> +<dt> <strong>VM_SYNC_INVALIDATE</strong> +<dd> +Flushes pages in the range. Only precious pages are returned to +the memory manager unless either <strong>VM_SYNC_SYNCHRONOUS</strong> or +<strong>VM_SYNC_ASYNCHRONOUS</strong> is also set. +<p> +<dt> <strong>VM_SYNC_SYNCHRONOUS</strong> +<dd> +Writes dirty and precious pages back to the memory manager, +waits for pages to reach backing storage. +<p> +<dt> <strong>VM_SYNC_ASYNCHRONOUS</strong> +<dd> +Writes dirty and precious pages back to the memory manager, +returns without waiting for pages to reach backing storage. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_msync</strong> function synchronizes the contents of +a memory range with its +backing store image by flushing or cleaning the contents of the +specified range +to the range's memory manager, engaging in a synchronization protocol with +the manager (<strong>memory_object_synchronize</strong>). +The client does not return from +this call until the memory manager responds (to the kernel) with +<strong>memory_object_synchronize_completed</strong>. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +The address is illegal or specifies a non-allocated region. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>, +<a href="MO_SY_completed.html"><strong>memory_object_synchronize_completed</strong></a>. diff --git a/osfmk/man/vm_protect.html b/osfmk/man/vm_protect.html index af0327ecf..8154ed724 100755 --- a/osfmk/man/vm_protect.html +++ b/osfmk/man/vm_protect.html @@ -1 +1,110 @@ -<h2>vm_protect</h2> <hr> <p> <strong>Function</strong> - Set access privilege attribute for a region of virtual memory. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_protect</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>boolean_t</strong> <var>set_maximum</var>, <strong>vm_prot_t</strong> <var>new_protection</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task whose address space contains the region. <p> <dt> <var>address</var> <dd> [in scalar] The starting address for the region. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes in the region. <p> <dt> <var>set_maximum</var> <dd> [in scalar] Maximum/current indicator. If true, the new protection sets the maximum protection for the region. If false, the new protection sets the current protection for the region. If the maximum protection is set below the current protection, the current protection is also reset to the new maximum. <p> <dt> <var>new_protection</var> <dd> [in scalar] The new protection for the region. Valid values are obtained by or'ing together the following values: <dl> <p> <dt> <strong>VM_PROT_READ</strong> <dd> Allows read access. <p> <dt> <strong>VM_PROT_WRITE</strong> <dd> Allows write access. <p> <dt> <strong>VM_PROT_EXECUTE</strong> <dd> Allows execute access. </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_protect</strong> function sets access privileges for a region within the specified task's address space. The <var>new_protection</var> parameter specifies a combination of read, write, and execute accesses that are allowed (rather than prohibited). <p> The region starts at the beginning of the virtual page containing <var>address</var>; it ends at the end of the virtual page containing <var>address</var> + <var>size</var> - 1. Because of this rounding to virtual page boundaries, the amount of memory protected may be greater than <var>size</var>. Use <strong>host_page_size</strong> to find the current virtual page size. <p> The enforcement of virtual memory protection is machine-dependent. Nominally read access requires <strong>VM_PROT_READ</strong> permission, write access requires <strong>VM_PROT_WRITE</strong> permission, and execute access requires <strong>VM_PROT_EXECUTE</strong> permission. However, some combinations of access rights may not be supported. In particular, the kernel interface allows write access to require <strong>VM_PROT_READ</strong> and <strong>VM_PROT_WRITE</strong> permission and execute access to require <strong>VM_PROT_READ</strong> permission. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_PROTECTION_FAILURE</strong> <dd> The new protection increased the current or maximum protection beyond the existing maximum protection. <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> The address is illegal or specifies a non-allocated region. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="host_page_size.html"><strong>host_page_size</strong></a>, <a href="vm_inherit.html"><strong>vm_inherit</strong></a>, <a href="vm_region.html"><strong>vm_region</strong></a>. \ No newline at end of file +<h2>vm_protect</h2> +<hr> +<p> +<strong>Function</strong> - Set access privilege attribute for a region of virtual memory. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_protect</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>boolean_t</strong> <var>set_maximum</var>, + <strong>vm_prot_t</strong> <var>new_protection</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task whose address space contains +the region. +<p> +<dt> <var>address</var> +<dd> +[in scalar] +The starting address for the region. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes in the region. +<p> +<dt> <var>set_maximum</var> +<dd> +[in scalar] +Maximum/current indicator. If true, the new protection sets +the maximum protection for the region. If false, the new protection sets +the current protection for the region. If the maximum protection is set +below the current protection, the current protection is also + reset to the new +maximum. +<p> +<dt> <var>new_protection</var> +<dd> +[in scalar] +The new protection for the region. Valid values are obtained +by or'ing together the following values: +<dl> +<p> +<dt> <strong>VM_PROT_READ</strong> +<dd> +Allows read access. +<p> +<dt> <strong>VM_PROT_WRITE</strong> +<dd> +Allows write access. +<p> +<dt> <strong>VM_PROT_EXECUTE</strong> +<dd> +Allows execute access. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_protect</strong> function sets access privileges for +a region within the specified +task's address space. +The <var>new_protection</var> parameter specifies a combination +of read, write, and +execute accesses that are allowed (rather than prohibited). +<p> +The region starts at the beginning of the virtual page containing +<var>address</var>; it ends +at the end of the virtual page containing <var>address</var> + +<var>size</var> - 1. Because of this +rounding to virtual page boundaries, the amount of memory protected may be +greater than <var>size</var>. Use <strong>host_page_size</strong> +to find the current virtual page size. +<p> +The enforcement of virtual memory protection is machine-dependent. +Nominally read access requires <strong>VM_PROT_READ</strong> permission, +write access requires +<strong>VM_PROT_WRITE</strong> permission, and execute access requires +<strong>VM_PROT_EXECUTE</strong> permission. However, some combinations +of access rights may not be +supported. In particular, the kernel interface allows write access to require +<strong>VM_PROT_READ</strong> and <strong>VM_PROT_WRITE</strong> permission and execute access to +require <strong>VM_PROT_READ</strong> permission. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_PROTECTION_FAILURE</strong> +<dd> +The new protection increased the current or maximum protection +beyond the existing maximum protection. +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +The address is illegal or specifies a non-allocated region. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="host_page_size.html"><strong>host_page_size</strong></a>, +<a href="vm_inherit.html"><strong>vm_inherit</strong></a>, +<a href="vm_region.html"><strong>vm_region</strong></a>. diff --git a/osfmk/man/vm_read.html b/osfmk/man/vm_read.html index 008f43ac6..ec6bba323 100755 --- a/osfmk/man/vm_read.html +++ b/osfmk/man/vm_read.html @@ -1 +1,87 @@ -<h2>vm_read</h2> <hr> <p> <strong>Function</strong> - Read the specified range of target task's address space. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_read</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>size</strong> <var>data_out</var>, <strong>target_task</strong> <var>data_count</var><strong>);</strong> </pre> <h4>Overwrite form:</h4> <pre> <strong>kern_return_t vm_read_overwrite</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>pointer_t</strong> <var>data_in</var>, <strong>target_task</strong> <var>data_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task whose memory is to be read. <p> <dt> <var>address</var> <dd> [in scalar] The address at which to start the read. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes to read. <p> <dt> <var>data_out</var> <dd> Out-pointer to dynamic array of bytes returned by the read. <p> <dt> <var>data_in</var> <dd> In-pointer to array of bytes that will be overwritten with the data returned by the read. <p> <dt> <var>data_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_read</strong> and <strong>vm_read_overwrite</strong> functions read a portion of a task's virtual memory (they enable tasks to read other tasks' memory). The <strong>vm_read</strong> function returns the data in a dynamically allocated array of bytes; the <strong>vm_read_overwrite</strong> function places the data into a caller-specified buffer (the <var>data_in</var> parameter). <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_PROTECTION_FAILURE</strong> <dd> Specified memory is valid, but does not permit reading. <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> The address is illegal or specifies a non-allocated region, or there are less than <var>size</var> bytes of data following the address, or the region specified by the <var>data_in</var> parameter cannot be written to. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_copy.html"><strong>vm_copy</strong></a>, <a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, <a href="vm_write.html"><strong>vm_write</strong></a>. \ No newline at end of file +<h2>vm_read</h2> +<hr> +<p> +<strong>Function</strong> - Read the specified range of target task's address space. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_read</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>size</strong> <var>data_out</var>, + <strong>target_task</strong> <var>data_count</var><strong>);</strong> +</pre> + +<h4>Overwrite form:</h4> +<pre> +<strong>kern_return_t vm_read_overwrite</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>pointer_t</strong> <var>data_in</var>, + <strong>target_task</strong> <var>data_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task whose memory is to be read. +<p> +<dt> <var>address</var> +<dd> +[in scalar] +The address at which to start the read. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes to read. +<p> +<dt> <var>data_out</var> +<dd> +Out-pointer to dynamic array of bytes returned by the read. +<p> +<dt> <var>data_in</var> +<dd> +In-pointer to array of bytes that will be overwritten with the data returned by the read. +<p> +<dt> <var>data_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_read</strong> and <strong>vm_read_overwrite</strong> +functions read a portion of a task's virtual +memory (they enable tasks to read other tasks' memory). +The <strong>vm_read</strong> function returns the data in a dynamically +allocated array of bytes; the <strong>vm_read_overwrite</strong> function +places the data into a caller-specified buffer (the <var>data_in</var> +parameter). +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_PROTECTION_FAILURE</strong> +<dd> +Specified memory is valid, but does not permit reading. +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +The address is illegal or specifies a non-allocated region, or there are +less than <var>size</var> bytes of data following the address, or the region +specified by the <var>data_in</var> parameter cannot be written to. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_copy.html"><strong>vm_copy</strong></a>, +<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, +<a href="vm_write.html"><strong>vm_write</strong></a>. diff --git a/osfmk/man/vm_region.html b/osfmk/man/vm_region.html index c36fd60f1..9d1a7c3e6 100755 --- a/osfmk/man/vm_region.html +++ b/osfmk/man/vm_region.html @@ -1 +1,96 @@ -<h2>vm_region</h2> <hr> <p> <strong>Function</strong> - Return description of a virtual memory region. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_region</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>vm_region_flavor_t</strong> <var>flavor</var>, <strong>vm_region_info_t</strong> <var>info</var>, <strong>mach_msg_type_number_t</strong> <var>info_count</var>, <strong>memory_object_name_t</strong> <var>object_name</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task whose address space contains the region. <p> <dt> <var>address</var> <dd> [pointer to in/out scalar] The address at which to start looking for a region. The function returns the starting address actually used. <p> <dt> <var>size</var> <dd> [out scalar] The number of bytes in the located region. The number converts to an integral number of virtual pages. <p> <dt> <var>flavor</var> <dd> [in scalar] The type of information to be returned. Valid values are: <dl> <p> <dt> <strong>VM_REGION_BASIC_INFO</strong> <dd> Basic information about the region (size, inheritance, etc.). This information is declared by the <strong>vm_region_basic_info</strong> structure. </dl> <p> <dt> <var>info</var> <dd> [out structure] Returned region information. <p> <dt> <var>info_count</var> <dd> [in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units). <p> <dt> <var>object_name</var> <dd> This parameter is no longer used. </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_region</strong> function returns information on a region within the specified task's address space. The function begins looking at <var>address</var> and continues until it finds an allocated region. If the input address is within a region, the function uses the start of that region. The starting address for the located region is returned in <var>address</var>. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> There is no region at or beyond the specified starting address. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_allocate.html"><strong>vm_allocate</strong></a>, <a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, <a href="vm_inherit.html"><strong>vm_inherit</strong></a>, <a href="vm_protect.html"><strong>vm_protect</strong></a>, <a href="vm_behavior_set.html"><strong>vm_behavior_set</strong></a>. <p> Data Structures: <a href="vm_region_basic_info.html"><strong>vm_region_basic_info</strong></a>. \ No newline at end of file +<h2>vm_region</h2> +<hr> +<p> +<strong>Function</strong> - Return description of a virtual memory region. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_region</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>vm_region_flavor_t</strong> <var>flavor</var>, + <strong>vm_region_info_t</strong> <var>info</var>, + <strong>mach_msg_type_number_t</strong> <var>info_count</var>, + <strong>memory_object_name_t</strong> <var>object_name</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task whose address space contains +the region. +<p> +<dt> <var>address</var> +<dd> +[pointer to in/out scalar] +The address at which to start looking for a +region. The function returns the starting address actually used. +<p> +<dt> <var>size</var> +<dd> +[out scalar] +The number of bytes in the located region. The number +converts to an integral number of virtual pages. +<p> +<dt> <var>flavor</var> +<dd> +[in scalar] +The type of information to be returned. Valid values are: +<dl> +<p> +<dt> <strong>VM_REGION_BASIC_INFO</strong> +<dd> +Basic information about the region (size, inheritance, etc.). +This information is declared by the + <strong>vm_region_basic_info</strong> structure. +</dl> +<p> +<dt> <var>info</var> +<dd> +[out structure] +Returned region information. +<p> +<dt> <var>info_count</var> +<dd> +[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +<p> +<dt> <var>object_name</var> +<dd> + This parameter is no longer used. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_region</strong> function returns information on a region +within the specified +task's address space. +The function begins looking at <var>address</var> and continues until it +finds an allocated +region. If the input address is within a region, the function +uses the start of that +region. The starting address for the located region is returned in <var>address</var>. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +There is no region at or beyond the specified starting address. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_allocate.html"><strong>vm_allocate</strong></a>, +<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, +<a href="vm_inherit.html"><strong>vm_inherit</strong></a>, +<a href="vm_protect.html"><strong>vm_protect</strong></a>, +<a href="vm_behavior_set.html"><strong>vm_behavior_set</strong></a>. +<p> +Data Structures: +<a href="vm_region_basic_info.html"><strong>vm_region_basic_info</strong></a>. diff --git a/osfmk/man/vm_region_basic_info.html b/osfmk/man/vm_region_basic_info.html index 85fcd3058..2522fe0e5 100755 --- a/osfmk/man/vm_region_basic_info.html +++ b/osfmk/man/vm_region_basic_info.html @@ -1 +1,80 @@ -<h2>vm_region_basic_info</h2> <hr> <p> <strong>Structure</strong> - Defines the attributes of a task's memory region. <h3>SYNOPSIS</h3> <pre> <strong>struct vm_region_basic_info</strong> <strong>{</strong> <strong>vm_prot_t</strong> <var>protection</var><strong>;</strong> <strong>vm_prot_t</strong> <var>max_protection</var><strong>;</strong> <strong>vm_inherit_t</strong> <var>inheritance</var><strong>;</strong> <strong>boolean_t</strong> <var>shared</var><strong>;</strong> <strong>boolean_t</strong> <var>reserved</var><strong>;</strong> <strong>vm_offset_t</strong> <var>offset</var><strong>;</strong> <strong>vm_behavior_t</strong> <var>behavior</var><strong>;</strong> <strong>unsigned short</strong> <var>user_wired_count</var><strong>;</strong> <strong>};</strong> <strong>typedef struct vm_region_basic_info* vm_region_basic_info_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>protection</var> <dd> The current protection for the region. <p> <dt> <var>max_protection</var> <dd> The maximum protection allowed for the region. <p> <dt> <var>inheritance</var> <dd> The inheritance attribute for the region. <p> <dt> <var>shared</var> <dd> Shared indicator. If true, the region is shared by another task. If false, the region is not shared. <p> <dt> <var>reserved</var> <dd> If true the region is protected from random allocation. <p> <dt> <var>offset</var> <dd> The region's offset into the memory object. The region begins at this offset. <p> <dt> <var>behavior</var> <dd> Expected reference pattern for the memory. Valid values are: <dl> <p> <dt> <strong>VM_BEHAVIOR_DEFAULT</strong> <dd> The system's default behavior. <p> <dt> <strong>VM_BEHAVIOR_RANDOM</strong> <dd> No particular order expected. <p> <dt> <strong>VM_BEHAVIOR_SEQUENTIAL</strong> <dd> Forward sequential order. <p> <dt> <strong>VM_BEHAVIOR_RSEQNTL</strong> <dd> Reverse sequential order. </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_region_basic_info</strong> structure defines the attributes of a memory region returned by <strong>vm_region</strong>. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_region.html"><strong>vm_region</strong></a>, <a href="vm_inherit.html"><strong>vm_inherit</strong></a>, <a href="vm_protect.html"><strong>vm_protect</strong></a>. \ No newline at end of file +<h2>vm_region_basic_info</h2> +<hr> +<p> +<strong>Structure</strong> - Defines the attributes of a task's memory region. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct vm_region_basic_info</strong> +<strong>{</strong> + <strong>vm_prot_t</strong> <var>protection</var><strong>;</strong> + <strong>vm_prot_t</strong> <var>max_protection</var><strong>;</strong> + <strong>vm_inherit_t</strong> <var>inheritance</var><strong>;</strong> + <strong>boolean_t</strong> <var>shared</var><strong>;</strong> + <strong>boolean_t</strong> <var>reserved</var><strong>;</strong> + <strong>vm_offset_t</strong> <var>offset</var><strong>;</strong> + <strong>vm_behavior_t</strong> <var>behavior</var><strong>;</strong> + <strong>unsigned short</strong> <var>user_wired_count</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct vm_region_basic_info* vm_region_basic_info_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>protection</var> +<dd> +The current protection for the region. +<p> +<dt> <var>max_protection</var> +<dd> +The maximum protection allowed for the region. +<p> +<dt> <var>inheritance</var> +<dd> +The inheritance attribute for the region. +<p> +<dt> <var>shared</var> +<dd> +Shared indicator. If true, the region is shared by another task. If false, +the region is not shared. +<p> +<dt> <var>reserved</var> +<dd> +If true the region is protected from random allocation. +<p> +<dt> <var>offset</var> +<dd> +The region's offset into the memory object. The region begins at this +offset. +<p> +<dt> <var>behavior</var> +<dd> +Expected reference pattern for the memory. Valid values are: +<dl> +<p> +<dt> <strong>VM_BEHAVIOR_DEFAULT</strong> +<dd> +The system's default behavior. +<p> +<dt> <strong>VM_BEHAVIOR_RANDOM</strong> +<dd> +No particular order expected. +<p> +<dt> <strong>VM_BEHAVIOR_SEQUENTIAL</strong> +<dd> +Forward sequential order. +<p> +<dt> <strong>VM_BEHAVIOR_RSEQNTL</strong> +<dd> +Reverse sequential order. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_region_basic_info</strong> structure defines the attributes +of a memory region returned by <strong>vm_region</strong>. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_region.html"><strong>vm_region</strong></a>, +<a href="vm_inherit.html"><strong>vm_inherit</strong></a>, +<a href="vm_protect.html"><strong>vm_protect</strong></a>. diff --git a/osfmk/man/vm_remap.html b/osfmk/man/vm_remap.html index 000f17103..33a165dc4 100755 --- a/osfmk/man/vm_remap.html +++ b/osfmk/man/vm_remap.html @@ -1 +1,193 @@ -<h2>vm_remap</h2> <hr> <p> <strong>Function</strong> - Map memory objects in one task's address space to that of another task's. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_remap</strong> <strong>(mach_port_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>target_address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>vm_address_t</strong> <var>mask</var>, <strong>boolean_t</strong> <var>anywhere</var>, <strong>mach_port_t</strong> <var>source_task</var>, <strong>vm_address_t</strong> <var>source_address</var>, <strong>boolean_t</strong> <var>copy</var>, <strong>vm_prot_t</strong> <var>cur_protection</var>, <strong>vm_prot_t</strong> <var>max_protection</var>, <strong>vm_inherit_t</strong> <var>inheritance</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <dt> <var>target_task</var> <dd> [in task send right] The port for the task in whose address space the memory is to be mapped. <p> <dt> <var>target_address</var> <dd> [pointer to in/out scalar] The starting address for the mapped memory in the target task. The mapped memory will start at the beginning of the page containing <var>target_address</var>. If there is not enough room following the address, the kernel does not map the memory. The kernel returns the starting address actually used for the mapped memory. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes to map. The kernel rounds this number up to an integral number of virtual pages. <p> <dt> <var>mask</var> <dd> [in scalar] Alignment restrictions for starting address. Bits turned on in the mask will not be turned on in the starting address. <p> <dt> <var>anywhere</var> <dd> [in scalar] Placement indicator. The valid values are: <dl> <p> <dt> <strong>TRUE</strong> <dd> The kernel allocates the region in the next unused space that is sufficient within the address space. The kernel returns the starting address actually used in <var>address</var>. <p> <dt> <strong>FALSE</strong> <dd> The kernel allocates the region starting at <var>address</var> unless that space is already allocated. </dl> <p> <dt> <var>source_task</var> <dd> [in task send right] The port for the task whose address space is to be mapped. <p> <dt> <var>source_address</var> <dd> [in scalar] The starting address for the memory to be mapped from the source task. The memory to be mapped will start at the beginning of the page containing <var>source_address</var>. If not enough memory exists following the address, the kernel does not map the memory. <p> <dt> <var>copy</var> <dd> [in scalar] Copy indicator. If true, the kernel copies the region for the memory to the specified task's address space. If false, the region is mapped read-write. <p> <dt> <var>cur_protection</var> <dd> [out scalar] The most restrictive current protection for the memory in the region. Valid values are obtained by or'ing together the following values: <dl> <p> <dt> <strong>VM_PROT_READ</strong> <dd> Allows read access. <p> <dt> <strong>VM_PROT_WRITE</strong> <dd> Allows write access. <p> <dt> <strong>VM_PROT_EXECUTE</strong> <dd> Allows execute access. </dl> <p> <dt> <var>max_protection</var> <dd> [out scalar] The most restrictive maximum protection for the memory in the region. Values are the same as for <var>cur_protection</var>. <p> <dt> <var>inheritance</var> <dd> [in scalar] The initial inheritance attribute for the region. Valid values are: <dl> <p> <dt> <strong>VM_INHERIT_SHARE</strong> <dd> Allows child tasks to share the region. <p> <dt> <strong>VM_INHERIT_COPY</strong> <dd> Gives child tasks a copy of the region. <p> <dt> <strong>VM_INHERIT_NONE</strong> <dd> Provides no access to the region for child tasks. </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_remap</strong> function maps the memory objects underlying a portion of the specified <var>source_task</var>'s virtual address space into the address space belonging to <var>target_task</var>. The target task can be the calling task or another task, identified by its task kernel port. The effect is as if the target task performed a <strong>vm_map</strong> call given the same memory object, maximum protection, current protection, and inheritance as the source task. However, the two tasks must reside on the same host. The kernel maps the memory objects starting at <var>target_address</var>, so that access to <var>target_address</var> is as if the source task accessed its <var>source_address</var>. <p> The <var>mask</var> parameter specifies additional alignment restrictions on the kernel's selection of the starting address. Uses for this mask include: <ul> <li> Forcing the memory address alignment for a mapping to be the same as the alignment within the source task. <li> Quickly finding the beginning of an allocated region by performing bit arithmetic on an address known to be in the region. <li> Emulating a larger virtual page size. </ul> The <var>cur_protection</var> and <var>max_protection</var> parameters return the protection attributes for the mapped memory. If all memory within the range had the same attributes, these attributes are returned; otherwise the call returns the most restrictive values for any memory in the region. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_NO_SPACE</strong> <dd> There is not enough space in the task's address space to allocate the new region for the memory object. <p> <dt> <strong>KERN_PROTECTION_FAILURE</strong> <dd> Specified memory is valid, but the backing memory manager is not permitted by the requesting task. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_map.html"><strong>vm_map</strong></a>, <a href="vm_read.html"><strong>vm_read</strong></a>, <a href="vm_write.html"><strong>vm_write</strong></a>. \ No newline at end of file +<h2>vm_remap</h2> +<hr> +<p> +<strong>Function</strong> - Map memory objects in one task's address space to that of another task's. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_remap</strong> + <strong>(mach_port_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>target_address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>vm_address_t</strong> <var>mask</var>, + <strong>boolean_t</strong> <var>anywhere</var>, + <strong>mach_port_t</strong> <var>source_task</var>, + <strong>vm_address_t</strong> <var>source_address</var>, + <strong>boolean_t</strong> <var>copy</var>, + <strong>vm_prot_t</strong> <var>cur_protection</var>, + <strong>vm_prot_t</strong> <var>max_protection</var>, + <strong>vm_inherit_t</strong> <var>inheritance</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task in whose address space the +memory is to be mapped. + <p> +<dt> <var>target_address</var> +<dd> +[pointer to in/out scalar] +The starting address for the mapped memory +in the target task. The mapped memory will start at the beginning of +the page containing <var>target_address</var>. If there is not enough room +following the address, the kernel does not map the memory. The kernel +returns the starting address actually used for the mapped memory. + <p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes to map. The kernel rounds this number +up to an integral number of virtual pages. +<p> +<dt> <var>mask</var> +<dd> +[in scalar] +Alignment restrictions for starting address. Bits turned on in +the mask will not be turned on in the starting address. +<p> +<dt> <var>anywhere</var> +<dd> +[in scalar] +Placement indicator. + The valid values are: +<dl> +<p> + <dt> <strong>TRUE</strong> +<dd> +The kernel allocates the region in the next unused space that +is sufficient within the address space. The kernel returns the +starting address actually used in <var>address</var>. +<p> +<dt> <strong>FALSE</strong> +<dd> +The kernel allocates the region starting at <var>address</var> unless that +space is already allocated. +</dl> +<p> +<dt> <var>source_task</var> +<dd> +[in task send right] +The port for the task whose address space is to be +mapped. +<p> +<dt> <var>source_address</var> +<dd> +[in scalar] +The starting address for the memory to be mapped from the +source task. The memory to be mapped will start at the beginning of +the page containing <var>source_address</var>. If not enough memory exists +following the address, the kernel does not map the memory. +<p> +<dt> <var>copy</var> +<dd> +[in scalar] +Copy indicator. If true, the kernel copies the region for the +memory to the specified task's address space. If false, the region is +mapped read-write. +<p> +<dt> <var>cur_protection</var> +<dd> +[out scalar] +The most restrictive current protection for the memory in +the region. Valid values are obtained by or'ing together the following +values: +<dl> +<p> + <dt> <strong>VM_PROT_READ</strong> +<dd> +Allows read access. +<p> +<dt> <strong>VM_PROT_WRITE</strong> +<dd> +Allows write access. +<p> +<dt> <strong>VM_PROT_EXECUTE</strong> +<dd> +Allows execute access. +</dl> +<p> +<dt> <var>max_protection</var> +<dd> +[out scalar] +The most restrictive maximum protection for the memory +in the region. Values are the same as for <var>cur_protection</var>. +<p> +<dt> <var>inheritance</var> +<dd> +[in scalar] +The initial inheritance attribute for the region. Valid values +are: +<dl> +<p> + <dt> <strong>VM_INHERIT_SHARE</strong> +<dd> +Allows child tasks to share the region. +<p> +<dt> <strong>VM_INHERIT_COPY</strong> +<dd> +Gives child tasks a copy of the region. +<p> +<dt> <strong>VM_INHERIT_NONE</strong> +<dd> +Provides no access to the region for child tasks. +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_remap</strong> function maps the memory objects underlying +a portion of the +specified <var>source_task</var>'s virtual address space into the address +space belonging to +<var>target_task</var>. The target task can be the calling task or another +task, identified by +its task kernel port. The effect is as if the target task performed +a <strong>vm_map</strong> call +given the same memory object, maximum protection, current +protection, and inheritance as the source task. +However, the two +tasks must reside on the same host. The kernel maps the memory objects +starting at <var>target_address</var>, so that access to <var>target_address</var> +is as if the source task +accessed its <var>source_address</var>. +<p> +The <var>mask</var> parameter +specifies additional alignment restrictions on the kernel's +selection of the starting address. Uses for this mask include: +<ul> +<li> +Forcing the memory address alignment for a mapping to be the same as the +alignment within the source task. +<li> +Quickly finding the beginning of an allocated region by performing bit +arithmetic on an address known to be in the region. +<li> +Emulating a larger virtual page size. +</ul> +The <var>cur_protection</var> and <var>max_protection</var> parameters return the protection +attributes for the mapped memory. If all memory within the range had the same +attributes, these attributes are returned; otherwise the call returns the most +restrictive values for any memory in the region. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> + <dt> <strong>KERN_NO_SPACE</strong> +<dd> +There is not enough space in the task's address space to allocate the +new region for the memory object. +<p> +<dt> <strong>KERN_PROTECTION_FAILURE</strong> +<dd> +Specified memory is valid, but the backing memory manager is +not permitted by the requesting task. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_map.html"><strong>vm_map</strong></a>, +<a href="vm_read.html"><strong>vm_read</strong></a>, +<a href="vm_write.html"><strong>vm_write</strong></a>. diff --git a/osfmk/man/vm_statistics.html b/osfmk/man/vm_statistics.html index cc72acccf..d16ac5599 100755 --- a/osfmk/man/vm_statistics.html +++ b/osfmk/man/vm_statistics.html @@ -1 +1,98 @@ -<h2>vm_statistics</h2> <hr> <p> <strong>Structure</strong> - Defines statistics for the kernel's use of virtual memory. <h3>SYNOPSIS</h3> <pre> <strong>struct vm_statistics</strong> <strong>{</strong> <strong>integer_t</strong> <var>free_count</var><strong>;</strong> <strong>integer_t</strong> <var>active_count</var><strong>;</strong> <strong>integer_t</strong> <var>inactive_count</var><strong>;</strong> <strong>integer_t</strong> <var>wire_count</var><strong>;</strong> <strong>integer_t</strong> <var>zero_fill_count</var><strong>;</strong> <strong>integer_t</strong> <var>reactivations</var><strong>;</strong> <strong>integer_t</strong> <var>pageins</var><strong>;</strong> <strong>integer_t</strong> <var>pageouts</var><strong>;</strong> <strong>integer_t</strong> <var>faults</var><strong>;</strong> <strong>integer_t</strong> <var>cow_faults</var><strong>;</strong> <strong>integer_t</strong> <var>lookups</var><strong>;</strong> <strong>integer_t</strong> <var>hits</var><strong>;</strong> <strong>};</strong> <strong>typedef struct vm_statistics* vm_statistics_t;</strong> </pre> <h3>FIELDS</h3> <dl> <dt> <var>free_count</var> <dd> The total number of free pages in the system. <p> <dt> <var>active_count</var> <dd> The total number of pages currently in use and pageable. <p> <dt> <var>inactive_count</var> <dd> The number of inactive pages. <p> <dt> <var>wire_count</var> <dd> The number of pages that are wired in memory and cannot be paged out. <p> <dt> <var>zero_fill_count</var> <dd> The number of zero-fill pages. <p> <dt> <var>reactivations</var> <dd> The number of reactivated pages. <p> <dt> <var>pageins</var> <dd> The number of requests for pages from a pager (such as the i-node pager). <p> <dt> <var>pageouts</var> <dd> The number of pages that have been paged out. <p> <dt> <var>faults</var> <dd> The number of times the <strong>vm_fault</strong> routine has been called. <p> <dt> <var>cow_faults</var> <dd> The number of copy-on-write faults. <p> <dt> <var>lookups</var> <dd> The number of object cache lookups. <p> <dt> <var>hits</var> <dd> The number of object cache hits. </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_statistics</strong> structure defines the statistics available on the kernel's use of virtual memory. The statistics record virtual memory usage since the kernel was booted. <p> For related information for a specific task, see the <strong>task_basic_info</strong> structure. <h3>NOTES</h3> <p> This structure is machine word length specific because of the memory sizes returned. <h3>RELATED INFORMATION</h3> <p> Functions: <a href="task_info.html"><strong>task_info</strong></a>, <a href="host_page_size.html"><strong>host_page_size</strong></a>. <p> Data Structures: <a href="task_basic_info.html"><strong>task_basic_info</strong></a>. \ No newline at end of file +<h2>vm_statistics</h2> +<hr> +<p> +<strong>Structure</strong> - Defines statistics for the kernel's use of virtual memory. +<h3>SYNOPSIS</h3> +<pre> +<strong>struct vm_statistics</strong> +<strong>{</strong> + <strong>integer_t</strong> <var>free_count</var><strong>;</strong> + <strong>integer_t</strong> <var>active_count</var><strong>;</strong> + <strong>integer_t</strong> <var>inactive_count</var><strong>;</strong> + <strong>integer_t</strong> <var>wire_count</var><strong>;</strong> + <strong>integer_t</strong> <var>zero_fill_count</var><strong>;</strong> + <strong>integer_t</strong> <var>reactivations</var><strong>;</strong> + <strong>integer_t</strong> <var>pageins</var><strong>;</strong> + <strong>integer_t</strong> <var>pageouts</var><strong>;</strong> + <strong>integer_t</strong> <var>faults</var><strong>;</strong> + <strong>integer_t</strong> <var>cow_faults</var><strong>;</strong> + <strong>integer_t</strong> <var>lookups</var><strong>;</strong> + <strong>integer_t</strong> <var>hits</var><strong>;</strong> +<strong>};</strong> + +<strong>typedef struct vm_statistics* vm_statistics_t;</strong> +</pre> +<h3>FIELDS</h3> +<dl> +<dt> <var>free_count</var> +<dd> +The total number of free pages in the system. +<p> +<dt> <var>active_count</var> +<dd> +The total number of pages currently in use and pageable. +<p> +<dt> <var>inactive_count</var> +<dd> +The number of inactive pages. +<p> +<dt> <var>wire_count</var> +<dd> +The number of pages that are wired in memory and cannot be paged +out. +<p> +<dt> <var>zero_fill_count</var> +<dd> +The number of zero-fill pages. +<p> +<dt> <var>reactivations</var> +<dd> +The number of reactivated pages. +<p> +<dt> <var>pageins</var> +<dd> +The number of requests for pages from a pager (such as the i-node +pager). +<p> +<dt> <var>pageouts</var> +<dd> +The number of pages that have been paged out. +<p> +<dt> <var>faults</var> +<dd> +The number of times the <strong>vm_fault</strong> routine has been called. +<p> +<dt> <var>cow_faults</var> +<dd> +The number of copy-on-write faults. +<p> +<dt> <var>lookups</var> +<dd> +The number of object cache lookups. +<p> +<dt> <var>hits</var> +<dd> +The number of object cache hits. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_statistics</strong> structure defines the statistics +available on the kernel's use of +virtual memory. The statistics record virtual memory usage since +the kernel was booted. +<p> +For related information for a specific task, see the <strong>task_basic_info</strong> +structure. +<h3>NOTES</h3> +<p> +This structure is machine word length specific because of the memory sizes +returned. +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="task_info.html"><strong>task_info</strong></a>, +<a href="host_page_size.html"><strong>host_page_size</strong></a>. +<p> +Data Structures: +<a href="task_basic_info.html"><strong>task_basic_info</strong></a>. + diff --git a/osfmk/man/vm_wire.html b/osfmk/man/vm_wire.html index 5a4e25952..466aebd59 100755 --- a/osfmk/man/vm_wire.html +++ b/osfmk/man/vm_wire.html @@ -1 +1,91 @@ -<h2>vm_wire</h2> <hr> <p> <strong>Function</strong> - Modify the target region's paging characteristics. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_wire</strong> <strong>(host_priv_t</strong> <var>host</var>, <strong>vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>vm_size_t</strong> <var>size</var>, <strong>vm_prot_t</strong> <var>wired_access</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>host</var> <dd> [in host-control send right] The control port for the host for which information is to be obtained. <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task whose address space contains the region. <p> <dt> <var>address</var> <dd> [in scalar] The starting address for the region. <p> <dt> <var>size</var> <dd> [in scalar] The number of bytes in the region. <p> <dt> <var>wired_access</var> <dd> [in scalar] The pageability of the region. The following values cause the region to be wired and protected as specified (values may be combined): <dl> <dt> <strong>VM_PROT_READ</strong> <dt> <strong>VM_PROT_WRITE</strong> <dt> <strong>VM_PROT_execute</strong> </dl> <p> The following value causes the region to be unwired (made pageable): <dl> <dt> <strong>VM_PROT_NONE</strong> </dl> </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_wire</strong> function sets the pageability privileges for a region within the specified task's address space. <var>wired_access</var> specifies the types of accesses to the memory region which must not suffer from (internal) faults of any kind after this call returns. A non-null <var>wired_access</var> value indicates that the page is to be "wired" into memory; a null value indicates "un-wiring". The kernel maintains for the region a count of the number of times the region is wired. A page is wired into physical memory if any task accessing it has a non-zero wired count for the page. <p> The region starts at the beginning of the virtual page containing <var>address</var>; it ends at the end of the virtual page containing <var>address</var> + <var>size</var> - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than <var>size</var>. Use <strong>host_page_size</strong> to find the current virtual page size. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> The address is illegal or specifies a non-allocated region. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="thread_wire.html"><strong>thread_wire</strong></a>. \ No newline at end of file +<h2>vm_wire</h2> +<hr> +<p> +<strong>Function</strong> - Modify the target region's paging characteristics. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_wire</strong> + <strong>(host_priv_t</strong> <var>host</var>, + <strong>vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>vm_size_t</strong> <var>size</var>, + <strong>vm_prot_t</strong> <var>wired_access</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>host</var> +<dd> +[in host-control send right] +The control port for the host for which +information is to be obtained. +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task whose address space contains +the region. +<p> +<dt> <var>address</var> +<dd> +[in scalar] +The starting address for the region. +<p> +<dt> <var>size</var> +<dd> +[in scalar] +The number of bytes in the region. +<p> +<dt> <var>wired_access</var> +<dd> +[in scalar] +The pageability of the region. The following values cause +the region to be wired and protected as specified +(values may be combined): +<dl> +<dt> <strong>VM_PROT_READ</strong> +<dt> <strong>VM_PROT_WRITE</strong> +<dt> <strong>VM_PROT_execute</strong> +</dl> +<p> +The following value causes the region to be unwired (made pageable): +<dl> +<dt> <strong>VM_PROT_NONE</strong> +</dl> +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_wire</strong> function sets the pageability privileges +for a region within the +specified task's address space. <var>wired_access</var> specifies the types +of accesses to +the memory region which must not suffer from (internal) faults +of any kind after +this call returns. A non-null <var>wired_access</var> value indicates that +the page is to be +"wired" into memory; a null value indicates "un-wiring". The kernel maintains +for the region a count of the number of times the region is wired. A page is +wired into physical memory if any task accessing it has a non-zero wired count +for the page. +<p> +The region starts at the beginning of the virtual page containing +<var>address</var>; it ends at the end of the virtual page containing +<var>address</var> + <var>size</var> - 1. Because of this +rounding to virtual page boundaries, the amount of memory affected may be +greater than <var>size</var>. Use <strong>host_page_size</strong> to find the current +virtual page size. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +The address is illegal or specifies a non-allocated region. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="thread_wire.html"><strong>thread_wire</strong></a>. diff --git a/osfmk/man/vm_write.html b/osfmk/man/vm_write.html index 6fe7f28e8..e0cf66420 100755 --- a/osfmk/man/vm_write.html +++ b/osfmk/man/vm_write.html @@ -1 +1,68 @@ -<h2>vm_write</h2> <hr> <p> <strong>Function</strong> - Write data to the specified address in the target task's address space. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t vm_write</strong> <strong>(vm_task_t</strong> <var>target_task</var>, <strong>vm_address_t</strong> <var>address</var>, <strong>pointer_t</strong> <var>data</var>, <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_task</var> <dd> [in task send right] The port for the task whose memory is to be written. <p> <dt> <var>address</var> <dd> [in scalar] The address at which to start the write. <p> <dt> <var>data</var> <dd> [pointer to page aligned in array of bytes] An array of data to be written. <p> <dt> <var>data_count</var> <dd> [in scalar] The number of bytes in the array. </dl> <h3>DESCRIPTION</h3> <p> The <strong>vm_write</strong> function writes an array of data to a task's virtual memory. It allows one task to write to another task's memory. <p> The result of <strong>vm_write</strong> is as if <var>target_task</var> had directly written into the set of pages. Hence, <var>target_task</var> must have write permission to the pages. <h3>NOTES</h3> <p> This interface is machine word length specific because of the virtual address parameter. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_PROTECTION_FAILURE</strong> <dd> Specified memory is valid, but does not permit writing. <p> <dt> <strong>KERN_INVALID_ADDRESS</strong> <dd> The address is illegal or specifies a non-allocated region. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="vm_copy.html"><strong>vm_copy</strong></a>, <a href="vm_protect.html"><strong>vm_protect</strong></a>, <a href="vm_read.html"><strong>vm_read</strong></a>, <a href="host_page_size.html"><strong>host_page_size</strong></a>. \ No newline at end of file +<h2>vm_write</h2> +<hr> +<p> +<strong>Function</strong> - Write data to the specified address in the target task's address space. +<h3>SYNOPSIS</h3> +<pre> +<strong>kern_return_t vm_write</strong> + <strong>(vm_task_t</strong> <var>target_task</var>, + <strong>vm_address_t</strong> <var>address</var>, + <strong>pointer_t</strong> <var>data</var>, + <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong> +</pre> +<h3>PARAMETERS</h3> +<dl> +<p> +<dt> <var>target_task</var> +<dd> +[in task send right] +The port for the task whose memory is to be +written. +<p> +<dt> <var>address</var> +<dd> +[in scalar] +The address at which to start the write. +<p> +<dt> <var>data</var> +<dd> +[pointer to page aligned in array of bytes] +An array of data to be +written. +<p> +<dt> <var>data_count</var> +<dd> +[in scalar] +The number of bytes in the array. +</dl> +<h3>DESCRIPTION</h3> +<p> +The <strong>vm_write</strong> function writes an array of data to a +task's virtual memory. It +allows one task to write to another task's memory. +<p> +The result of <strong>vm_write</strong> is as if <var>target_task</var> had directly +written into the set of +pages. Hence, <var>target_task</var> must have write permission to the pages. +<h3>NOTES</h3> +<p> +This interface is machine word length specific because of the virtual address +parameter. +<h3>RETURN VALUES</h3> +<dl> +<p> +<dt> <strong>KERN_PROTECTION_FAILURE</strong> +<dd> +Specified memory is valid, but does not permit writing. +<p> +<dt> <strong>KERN_INVALID_ADDRESS</strong> +<dd> +The address is illegal or specifies a non-allocated region. +</dl> +<h3>RELATED INFORMATION</h3> +<p> +Functions: +<a href="vm_copy.html"><strong>vm_copy</strong></a>, +<a href="vm_protect.html"><strong>vm_protect</strong></a>, +<a href="vm_read.html"><strong>vm_read</strong></a>, +<a href="host_page_size.html"><strong>host_page_size</strong></a>. diff --git a/osfmk/ppc/lowmem_vectors.s b/osfmk/ppc/lowmem_vectors.s index 54b63596f..1a14e5d94 100644 --- a/osfmk/ppc/lowmem_vectors.s +++ b/osfmk/ppc/lowmem_vectors.s @@ -130,7 +130,7 @@ rxCont: mtcr r11 li r11,RESET_HANDLER_IGNORE ; Get set to ignore stw r11,lo16(EXT(ResetHandler)-EXT(ExceptionVectorsStart)+RESETHANDLER_TYPE)(br0) ; Start ignoring these mfsprg r13,1 /* Get the exception save area */ - li r11,T_RESET /* Set 'rupt code */ + li r11,T_RESET /* Set interrupt code */ b .L_exception_entry /* Join common... */ /* @@ -223,7 +223,7 @@ notDCache: mtcrf 255,r13 ; Restore CRs .L_handler300: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_DATA_ACCESS /* Set 'rupt code */ + li r11,T_DATA_ACCESS /* Set interrupt code */ b .L_exception_entry /* Join common... */ @@ -279,7 +279,7 @@ notDCache: mtcrf 255,r13 ; Restore CRs .L_handler600: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_ALIGNMENT|T_FAM /* Set 'rupt code */ + li r11,T_ALIGNMENT|T_FAM /* Set interrupt code */ b .L_exception_entry /* Join common... */ /* @@ -303,7 +303,7 @@ notDCache: mtcrf 255,r13 ; Restore CRs mtcrf 255,r11 ; (BRINGUP) #endif - li r11,T_PROGRAM|T_FAM /* Set 'rupt code */ + li r11,T_PROGRAM|T_FAM /* Set interrupt code */ b .L_exception_entry /* Join common... */ /* @@ -314,7 +314,7 @@ notDCache: mtcrf 255,r13 ; Restore CRs .L_handler800: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_FP_UNAVAILABLE /* Set 'rupt code */ + li r11,T_FP_UNAVAILABLE /* Set interrupt code */ b .L_exception_entry /* Join common... */ @@ -326,7 +326,7 @@ notDCache: mtcrf 255,r13 ; Restore CRs .L_handler900: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_DECREMENTER /* Set 'rupt code */ + li r11,T_DECREMENTER /* Set interrupt code */ b .L_exception_entry /* Join common... */ /* @@ -337,7 +337,7 @@ notDCache: mtcrf 255,r13 ; Restore CRs .L_handlerA00: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_IO_ERROR /* Set 'rupt code */ + li r11,T_IO_ERROR /* Set interrupt code */ b .L_exception_entry /* Join common... */ /* @@ -348,7 +348,7 @@ notDCache: mtcrf 255,r13 ; Restore CRs .L_handlerB00: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_RESERVED /* Set 'rupt code */ + li r11,T_RESERVED /* Set interrupt code */ b .L_exception_entry /* Join common... */ @@ -385,7 +385,7 @@ notDCache: mtcrf 255,r13 ; Restore CRs rlwinm r11,r11,0,0,30 ; clear out bit 31 rlwimi r11,r13,1,0x40 ; move 0x6004 bit into position lhz r11,lo16(scTable)(r11) ; get branch address from sc table - mfctr r13 ; save caller's ctr in r13 + mfctr r13 ; save callers ctr in r13 mtctr r11 ; set up branch to syscall handler mfsprg r11,0 ; get per_proc, which most UFTs use bctr ; dispatch (r11 in sprg3, r13 in sprg2, ctr in r13, per_proc in r11) @@ -480,7 +480,7 @@ sbxx64c: ld r1,tempr0(r11) ; Restore work register .L_handlerE00: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_FP_ASSIST /* Set 'rupt code */ + li r11,T_FP_ASSIST /* Set interrupt code */ b .L_exception_entry /* Join common... */ @@ -492,7 +492,7 @@ sbxx64c: ld r1,tempr0(r11) ; Restore work register PMIhandler: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_PERF_MON /* Set 'rupt code */ + li r11,T_PERF_MON /* Set interrupt code */ b .L_exception_entry /* Join common... */ @@ -504,7 +504,7 @@ PMIhandler: VMXhandler: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_VMX /* Set 'rupt code */ + li r11,T_VMX /* Set interrupt code */ b .L_exception_entry /* Join common... */ @@ -555,7 +555,7 @@ VMXhandler: .L_handler1300: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_INSTRUCTION_BKPT /* Set 'rupt code */ + li r11,T_INSTRUCTION_BKPT /* Set interrupt code */ b .L_exception_entry /* Join common... */ /* @@ -566,7 +566,7 @@ VMXhandler: .L_handler1400: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_SYSTEM_MANAGEMENT /* Set 'rupt code */ + li r11,T_SYSTEM_MANAGEMENT /* Set interrupt code */ b .L_exception_entry /* Join common... */ @@ -578,7 +578,7 @@ VMXhandler: .L_handler1500: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_SOFT_PATCH /* Set 'rupt code */ + li r11,T_SOFT_PATCH /* Set interrupt code */ b .L_exception_entry /* Join common... */ ; @@ -589,7 +589,7 @@ VMXhandler: .L_handler1600: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_ALTIVEC_ASSIST /* Set 'rupt code */ + li r11,T_ALTIVEC_ASSIST /* Set interrupt code */ b .L_exception_entry /* Join common... */ ; @@ -600,7 +600,7 @@ VMXhandler: .L_handler1700: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_THERMAL /* Set 'rupt code */ + li r11,T_THERMAL /* Set interrupt code */ b .L_exception_entry /* Join common... */ ; @@ -611,7 +611,7 @@ VMXhandler: .L_handler1800: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_ARCHDEP0 /* Set 'rupt code */ + li r11,T_ARCHDEP0 /* Set interrupt code */ b .L_exception_entry /* Join common... */ /* @@ -626,7 +626,7 @@ VMXhandler: .L_handler2000: mtsprg 2,r13 /* Save R13 */ mtsprg 3,r11 /* Save R11 */ - li r11,T_INSTRUMENTATION /* Set 'rupt code */ + li r11,T_INSTRUMENTATION /* Set interrupt code */ b .L_exception_entry /* Join common... */ @@ -845,17 +845,17 @@ scTable: ; ABCD E * except the following: * * r11 = per_proc ptr (ie, sprg0) - * r13 = holds caller's ctr register - * sprg2 = holds caller's r13 - * sprg3 = holds caller's r11 + * r13 = holds callers ctr register + * sprg2 = holds callers r13 + * sprg3 = holds callers r11 */ ; Handle "vmm_dispatch" (0x6004), of which only some selectors are UFTs. uftVMM: - mtctr r13 ; restore caller's ctr + mtctr r13 ; restore callers ctr lwz r11,spcFlags(r11) ; get the special flags word from per_proc - mfcr r13 ; save caller's entire cr (we use all fields below) + mfcr r13 ; save callers entire cr (we use all fields below) rlwinm r11,r11,16,16,31 ; Extract spcFlags upper bits andi. r11,r11,hi16(runningVM|FamVMena|FamVMmode) cmpwi cr0,r11,hi16(runningVM|FamVMena|FamVMmode) ; Test in VM FAM @@ -871,9 +871,9 @@ uftVMM: uftIsPreemptiveTask: uftIsPreemptiveTaskEnv: - mtctr r13 ; restore caller's ctr + mtctr r13 ; restore callers ctr lwz r11,spcFlags(r11) ; get the special flags word from per_proc - mfcr r13,0x80 ; save caller's cr0 so we can use it + mfcr r13,0x80 ; save callers cr0 so we can use it andi. r11,r11,bbNoMachSC|bbPreemptive ; Clear what we do not need cmplwi r11,bbNoMachSC ; See if we are trapping syscalls blt-- uftNormal80 ; No... @@ -892,7 +892,7 @@ uftThreadInfo: lwz r3,UAW+4(r11) ; get user assist word, assuming a 32-bit processor LEXT(uft_uaw_nop_if_32bit) ld r3,UAW(r11) ; get the whole doubleword if 64-bit (patched to nop if 32-bit) - mtctr r13 ; restore caller's ctr + mtctr r13 ; restore callers ctr b uftRFI ; done @@ -900,16 +900,16 @@ LEXT(uft_uaw_nop_if_32bit) uftFacilityStatus: lwz r3,spcFlags(r11) ; get "special flags" word from per_proc - mtctr r13 ; restore caller's ctr + mtctr r13 ; restore callers ctr b uftRFI ; done ; Handle "Load MSR" UFT (0x7FF4). This is not used on 64-bit processors, though it would work. uftLoadMSR: - mfsrr1 r11 ; get caller's MSR - mtctr r13 ; restore caller's ctr - mfcr r13,0x80 ; save caller's cr0 so we can test PR + mfsrr1 r11 ; get callers MSR + mtctr r13 ; restore callers ctr + mfcr r13,0x80 ; save callers cr0 so we can test PR rlwinm. r11,r11,0,MSR_PR_BIT,MSR_PR_BIT ; really in the kernel? bne- uftNormal80 ; do not permit from user mode mfsprg r11,0 ; restore per_proc @@ -923,7 +923,7 @@ uftLoadMSR: ; sprg3 = callers r11 uftRestoreThenRFI: ; WARNING: can drop down to here - mtcrf 0x80,r13 ; restore caller's cr0 + mtcrf 0x80,r13 ; restore callers cr0 uftRFI: .globl EXT(uft_nop_if_32bit) LEXT(uft_nop_if_32bit) @@ -1031,7 +1031,7 @@ ctgte32tb: mftbu r21 ; Get the upper time now lhz r24,PP_CPU_NUMBER(r11) ; Get the logical processor number li r23,T_SYSTEM_CALL ; Get the system call id - mtctr r13 ; Restore the caller's CTR + mtctr r13 ; Restore the callers CTR sth r24,LTR_cpu(r20) ; Save processor number li r24,64 ; Offset to third line sth r23,LTR_excpt(r20) ; Set the exception code @@ -1081,7 +1081,7 @@ ctdisa32: mtcrf 0x80,r25 ; Restore the used condition register field lwz r20,tempr0(r11) ; Restore work register lwz r21,tempr1(r11) ; Restore work register lwz r25,tempr2(r11) ; Restore work register - mtctr r13 ; Restore the caller's CTR + mtctr r13 ; Restore the callers CTR lwz r22,tempr3(r11) ; Restore work register lwz r23,tempr4(r11) ; Restore work register lwz r24,tempr5(r11) ; Restore work register @@ -1091,7 +1091,7 @@ ctbail32: mtcrf 0x80,r25 ; Restore the used condition register field lwz r20,tempr0(r11) ; Restore work register lwz r21,tempr1(r11) ; Restore work register lwz r25,tempr2(r11) ; Restore work register - mtctr r13 ; Restore the caller's CTR + mtctr r13 ; Restore the callers CTR lwz r22,tempr3(r11) ; Restore work register lwz r23,tempr4(r11) ; Restore work register b uftNormalSyscall ; Go pass it on along... @@ -1199,7 +1199,7 @@ ctdisa64: mtcrf 0x80,r25 ; Restore the used condition register field ld r20,tempr0(r11) ; Restore work register ld r21,tempr1(r11) ; Restore work register ld r25,tempr2(r11) ; Restore work register - mtctr r13 ; Restore the caller's CTR + mtctr r13 ; Restore the callers CTR ld r22,tempr3(r11) ; Restore work register ld r23,tempr4(r11) ; Restore work register ld r24,tempr5(r11) ; Restore work register @@ -1209,7 +1209,7 @@ ctbail64: mtcrf 0x80,r25 ; Restore the used condition register field ld r20,tempr0(r11) ; Restore work register ld r21,tempr1(r11) ; Restore work register ld r25,tempr2(r11) ; Restore work register - mtctr r13 ; Restore the caller's CTR + mtctr r13 ; Restore the callers CTR ld r22,tempr3(r11) ; Restore work register ld r23,tempr4(r11) ; Restore work register li r11,T_SYSTEM_CALL|T_FAM ; Set system code call @@ -1241,8 +1241,8 @@ uftNormalSyscall1: * set up: * * ENTRY: interrupts off, VM off, in 64-bit mode if supported - * Caller's r13 saved in sprg2. - * Caller's r11 saved in sprg3. + * Callers r13 saved in sprg2. + * Callers r11 saved in sprg3. * Exception code (ie, T_SYSTEM_CALL etc) in r11. * All other registers are live. * @@ -1253,9 +1253,9 @@ uftNormalSyscall1: /* * * Here we will save off a mess of registers, the special ones and R0-R12. We use the DCBZ - * instruction to clear and allcoate a line in the cache. This way we won't take any cache - * misses, so these stores won't take all that long. Except the first line that is because - * we can't do a DCBZ if the L1 D-cache is off. The rest we will skip if they are + * instruction to clear and allcoate a line in the cache. This way we will not take any cache + * misses, so these stores will not take all that long. Except the first line that is because + * we can not do a DCBZ if the L1 D-cache is off. The rest we will skip if they are * off also. * * Note that if we are attempting to sleep (as opposed to nap or doze) all interruptions @@ -2970,9 +2970,9 @@ ueMck: li r0,0 ; Set the unrecovered flag before passing up /* - * Here's where we come back from some instruction emulator. If we come back with + * Here is where we come back from some instruction emulator. If we come back with * T_IN_VAIN, the emulation is done and we should just reload state and directly - * go back to the interrupted code. Otherwise, we'll check to see if + * go back to the interrupted code. Otherwise, we will check to see if * we need to redrive with a different interrupt, i.e., DSI. * Note that this we are actually not redriving the rupt, rather changing it * into a different one. Thus we clear the redrive bit. diff --git a/osfmk/ppc/machine_routines_asm.s b/osfmk/ppc/machine_routines_asm.s index afd81129a..15a93612f 100644 --- a/osfmk/ppc/machine_routines_asm.s +++ b/osfmk/ppc/machine_routines_asm.s @@ -2302,7 +2302,7 @@ spOver: mftbu r8 ; Get upper time andc r7,r7,r0 ; Pin time at 0 if under minimum subfe r2,r2,r2 ; 0 if diff > 2**32, -1 otherwise sub r7,r7,r10 ; Negative if duration is less than (max - min) - or r2,r2,r0 ; If the duration is negative, it isn't too big + or r2,r2,r0 ; If the duration is negative, it is not too big srawi r0,r7,31 ; -1 if duration is too small and r7,r7,r2 ; Clear duration if high part too big and r7,r7,r0 ; Clear duration if low part too big diff --git a/osfmk/ppc/mappings.c b/osfmk/ppc/mappings.c index 2f80bc88c..f5138334f 100644 --- a/osfmk/ppc/mappings.c +++ b/osfmk/ppc/mappings.c @@ -1526,6 +1526,19 @@ vm_offset_t kvtophys(vm_offset_t va) { } +/* + * kvtophys64(addr) + * + * Convert a kernel virtual address to a 64-bit physical address + */ +vm_map_offset_t kvtophys64(vm_map_offset_t va) { + ppnum_t pa = pmap_find_phys(kernel_pmap, (addr64_t)va); + + if (!pa) + return (vm_map_offset_t)0; + return (((vm_map_offset_t)pa) << 12) | (va & 0xfff); +} + /* * void ignore_zero_fault(boolean_t) - Sets up to ignore or honor any fault on * page 0 access for the current thread. diff --git a/osfmk/ppc/pmap.h b/osfmk/ppc/pmap.h index e8b137b64..3302ca747 100644 --- a/osfmk/ppc/pmap.h +++ b/osfmk/ppc/pmap.h @@ -278,6 +278,7 @@ extern pmapTransTab *pmapTrans; /* Space to pmap translate table */ */ extern vm_offset_t phystokv(vm_offset_t pa); /* Get kernel virtual address from physical */ extern vm_offset_t kvtophys(vm_offset_t va); /* Get physical address from kernel virtual */ +extern vm_map_offset_t kvtophys64(vm_map_offset_t va); /* Get 64-bit physical address from kernel virtual */ extern vm_offset_t pmap_map(vm_offset_t va, vm_offset_t spa, vm_offset_t epa, -- 2.45.2