From: Apple Date: Mon, 7 Aug 2006 22:20:11 +0000 (+0000) Subject: xnu-792.6.76.tar.gz X-Git-Tag: mac-os-x-1047ppc^0 X-Git-Url: https://git.saurik.com/apple/xnu.git/commitdiff_plain/13fec9890cf095cc781fdf7b8917cb03bf32dd4c xnu-792.6.76.tar.gz --- 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 - -#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 + +#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 -# elif defined( BSD ) && BSD >= 199103 -# include -# 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 -# if defined(__BEOS__) -# include -# 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 +# elif defined( BSD ) && BSD >= 199103 +# include +# 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 +# if defined(__BEOS__) +# include +# 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 + */ + 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 #include #include +#include #include #include @@ -54,6 +55,7 @@ #include #include +#include #include #include /* 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 @@ - -FTP Menu at ftp2.FreeBSD.ORG - -

FTP Menu

-
- -[TXT] README
- -[TXT] devfs_proto.h
- -[TXT] devfs_tree.c
- -[TXT] devfs_vfsops.c
- -[TXT] devfs_vnops.c
- -[TXT] devfsdefs.h
- -[TXT] reproto.sh
-
-http-gw version 3.2 / 0 - (17.254.0.77) + +FTP Menu at ftp2.FreeBSD.ORG + +

FTP Menu

+
+ +[TXT] README
+ +[TXT] devfs_proto.h
+ +[TXT] devfs_tree.c
+ +[TXT] devfs_vfsops.c
+ +[TXT] devfs_vnops.c
+ +[TXT] devfsdefs.h
+ +[TXT] reproto.sh
+
+http-gw version 3.2 / 0 + (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 +#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 @@ -

do_mach_notify_port_deleted

Server Interface - Handle the current instance of a port-deleted notification.

SYNOPSIS

kern_return_t   do_mach_notify_port_deleted
                (notify_port_t                           notify,
                 mach_port_name_t                          name);


kern_return_t   do_seqnos_mach_notify_port_deleted
                (notify_port_t                           notify,
                 mach_port_seqno_t                        seqno,
                 mach_port_name_t                          name);

PARAMETERS

notify
[in notify (receive) right] The port to which the notification was sent.

seqno
[in scalar] The sequence number of this message relative to the notification port.

name
[in scalar] The invalid name.

DESCRIPTION

A do_mach_notify_port_deleted function is called by notify_server 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. notify is the port named via mach_port_request_notification or mach_msg.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: notify_server, seqnos_notify_server, mach_msg, mach_port_request_notification, do_mach_notify_dead_name, do_mach_notify_no_senders, do_mach_notify_send_once. \ No newline at end of file +

do_mach_notify_port_deleted

+
+

+Server Interface - Handle the current instance of a port-deleted notification. +

SYNOPSIS

+
+kern_return_t   do_mach_notify_port_deleted
+                (notify_port_t                           notify,
+                 mach_port_name_t                          name);
+
+
+kern_return_t   do_seqnos_mach_notify_port_deleted
+                (notify_port_t                           notify,
+                 mach_port_seqno_t                        seqno,
+                 mach_port_name_t                          name);
+
+

PARAMETERS

+
+

+

notify +
+[in notify (receive) right] +The port to which the notification was sent. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the +notification port. +

+

name +
+[in scalar] +The invalid name. +
+

DESCRIPTION

+

+A do_mach_notify_port_deleted function is called by +notify_server 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. +notify is the port named via mach_port_request_notification +or mach_msg. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +notify_server, +seqnos_notify_server, +mach_msg, +mach_port_request_notification, +do_mach_notify_dead_name, +do_mach_notify_no_senders, +do_mach_notify_send_once. 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 @@ -

do_mach_notify_port_destroyed

Server Interface - Handle the current instance of a port-destroyed notification.

SYNOPSIS

kern_return_t   do_mach_notify_port_destroyed
                (notify_port_t                           notify,
                 mach_port_receive_t                       name);


kern_return_t   do_seqnos_mach_notify_port_destroyed
                (mach_port_t                             notify,
                 mach_port_seqno_t                        seqno,
                 mach_port_receive_t                       name);

PARAMETERS

notify
[in notify (receive) right] The port to which the notification was sent.

seqno
[in scalar] The sequence number of this message relative to the notification port.

name
[in scalar] The invalid name.

DESCRIPTION

A do_mach_notify_port_destroyed function is called by notify_server as the result of a kernel message indicating that a receive right would have been destroyed. notify is the port named via mach_port_request_notification or mach_msg.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: notify_server, seqnos_notify_server, mach_msg, mach_port_request_notification, do_mach_notify_dead_name, do_mach_notify_no_senders, do_mach_notify_send_once. \ No newline at end of file +

do_mach_notify_port_destroyed

+
+

+Server Interface - Handle the current instance of a port-destroyed notification. +

SYNOPSIS

+
+kern_return_t   do_mach_notify_port_destroyed
+                (notify_port_t                           notify,
+                 mach_port_receive_t                       name);
+
+
+kern_return_t   do_seqnos_mach_notify_port_destroyed
+                (mach_port_t                             notify,
+                 mach_port_seqno_t                        seqno,
+                 mach_port_receive_t                       name);
+
+

PARAMETERS

+
+

+

notify +
+[in notify (receive) right] +The port to which the notification was sent. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the +notification port. +

+

name +
+[in scalar] +The invalid name. +
+

DESCRIPTION

+

+A do_mach_notify_port_destroyed function is called by +notify_server as the +result of a kernel message indicating that a receive right would have +been destroyed. notify is the port named via +mach_port_request_notification or mach_msg. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +notify_server, +seqnos_notify_server, +mach_msg, +mach_port_request_notification, +do_mach_notify_dead_name, +do_mach_notify_no_senders, +do_mach_notify_send_once. 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 @@ -

default_pager_backing_store_create

Server Interface - Create a backing storage object.

SYNOPSIS

#include< mach/default_pager_object.h>

kern_return_t   default_pager_backing_store_create
                (mach_port_t                              pager,
                 int                                   priority,
                 int                                     clsize,
                 mach_port_t                      backing_store);

PARAMETERS

pager
[in default pager (receive) right] The default pager service port.

priority
[in scalar] The scheduling priority for the backing store service thread(s).

clsize
[in scalar] The preferred cluster size (in bytes) for the backing store object.

backing_store
[out backing store (receive) right] The port used to manipulate the created backing store.

DESCRIPTION

The default_pager_backing_store_create 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.

RETURN VALUES

KERN_FAILURE
The default pager does not support this operation.

KERN_INVALID_ARGUMENT
The pager port does not represent a valid default pager.

KERN_SUCCESS
The operation was successful.

RELATED INFORMATION

Functions: default_pager_backing_store_delete, default_pager_backing_store_info. \ No newline at end of file +

default_pager_backing_store_create

+
+

+Server Interface - Create a backing storage object. +

SYNOPSIS

+
+#include< mach/default_pager_object.h>
+
+kern_return_t   default_pager_backing_store_create
+                (mach_port_t                              pager,
+                 int                                   priority,
+                 int                                     clsize,
+                 mach_port_t                      backing_store);
+
+

PARAMETERS

+
+

+

pager +
+[in default pager (receive) right] The default pager service port. +

+

priority +
+[in scalar] The scheduling priority for the backing store service +thread(s). +

+

clsize +
+[in scalar] The preferred cluster size (in bytes) for the backing +store object. +

+

backing_store +
+[out backing store (receive) right] The port used to manipulate the +created backing store. +
+

DESCRIPTION

+

+The default_pager_backing_store_create 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. +

RETURN VALUES

+
+

+

KERN_FAILURE +
+The default pager does not support this operation. +

+

KERN_INVALID_ARGUMENT +
+The pager port does not represent a valid default pager. +

+

KERN_SUCCESS +
+The operation was successful. +
+

RELATED INFORMATION

+

+Functions: +default_pager_backing_store_delete, +default_pager_backing_store_info. 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 @@ -

default_pager_backing_store_delete

Server Interface - Delete a backing storage object.

SYNOPSIS

#include< mach/default_pager_object.h>

kern_return_t   default_pager_backing_store_delete
                (mach_port_t                      backing_store);

PARAMETERS

backing_store
[in backing store (receive) right] The backing store port created by default_pager_backing_store_create.

DESCRIPTION

The default_pager_backing_store_delete function is called to destroy a backing storage object created by default_pager_backing_store_create. 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 default_pager_backing_store_create, for a default memory manager.

RETURN VALUES

KERN_FAILURE
The default pager does not support this operation.

KERN_INVALID_ARGUMENT
The backing_store port does not represent a valid backing store or the specified segment overlaps an existing partition.

KERN_SUCCESS
The operation was successful.

RELATED INFORMATION

Functions: default_pager_backing_store_create, default_pager_backing_store_info. \ No newline at end of file +

default_pager_backing_store_delete

+
+

+Server Interface - Delete a backing storage object. +

SYNOPSIS

+
+#include< mach/default_pager_object.h>
+
+kern_return_t   default_pager_backing_store_delete
+                (mach_port_t                      backing_store);
+
+

PARAMETERS

+
+

+

backing_store +
+[in backing store (receive) right] The backing store port created by +default_pager_backing_store_create. +
+

DESCRIPTION

+

+The default_pager_backing_store_delete function is called to destroy a +backing storage object created by +default_pager_backing_store_create. 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 +default_pager_backing_store_create, for a default memory manager. +

RETURN VALUES

+
+

+

KERN_FAILURE +
+The default pager does not support this operation. +

+

KERN_INVALID_ARGUMENT +
+The backing_store port does not represent a valid backing store or the +specified segment overlaps an existing partition. +

+

KERN_SUCCESS +
+The operation was successful. +
+

RELATED INFORMATION

+

+Functions: +default_pager_backing_store_create, +default_pager_backing_store_info. 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 @@ -

default_pager_backing_store_info

Server Interface - Return information about a backing storage object.

SYNOPSIS

#include< default_pager/mach/default_pager_types.h>

kern_return_t   default_pager_backing_store_info
                (mach_port_t                      backing_store,
                 backing_store_flavor_t                  flavor,
                 backing_store_info_t                      info,
                 mach_msg_type_number_t                    size);

PARAMETERS

backing_store
[in backing store (receive) right] The backing store port for which information is desired.

flavor
[in scalar] The type of information to be returned. Valid values are:

BACKING_STORE_BASIC_INFO
Statistical and space used/available information. It includes the priority and cluster size that was provided in the default_pager_backing_store_create call.

info
[pointer to in structure] The data structure that will be filled in with the information provided for the requested flavor.

size
[pointer to in/out scalar] On input, the maximum size of the info data structure; on output, the actual size of the returned data.

DESCRIPTION

The default_pager_backing_store_info function is called to obtain information about a backing storage object created by default_pager_backing_store_create. 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 default_pager_backing_store_create, for a default memory manager.

RETURN VALUES

KERN_FAILURE
The default pager does not support this operation.

KERN_INVALID_ARGUMENT
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.

KERN_SUCCESS
The operation was successful.

RELATED INFORMATION

Functions: default_pager_backing_store_create, default_pager_backing_store_delete.

Data Structures: backing_store_basic_info. \ No newline at end of file +

default_pager_backing_store_info

+
+

+Server Interface - Return information about a backing storage object. +

SYNOPSIS

+
+#include< default_pager/mach/default_pager_types.h>
+
+kern_return_t   default_pager_backing_store_info
+                (mach_port_t                      backing_store,
+                 backing_store_flavor_t                  flavor,
+                 backing_store_info_t                      info,
+                 mach_msg_type_number_t                    size);
+
+

PARAMETERS

+
+

+

backing_store +
+[in backing store (receive) right] The backing store port for which +information is desired. +

+

flavor +
+[in scalar] The type of information to be returned. Valid values are: +

+

BACKING_STORE_BASIC_INFO +
+Statistical and space used/available information. It includes +the priority and cluster size that was provided in the +default_pager_backing_store_create call. +

+

info +
+[pointer to in structure] The data structure that will be filled in with the +information provided for the requested flavor. +

+

size +
+[pointer to in/out scalar] On input, the maximum size of the info data +structure; on output, the actual size of the returned data. +
+

DESCRIPTION

+

+The default_pager_backing_store_info function is called to obtain +information about a backing storage object created by +default_pager_backing_store_create. 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 +default_pager_backing_store_create, for a default memory manager. +

RETURN VALUES

+
+

+

KERN_FAILURE +
+The default pager does not support this operation. +

+

KERN_INVALID_ARGUMENT +
+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. +

+

KERN_SUCCESS +
+The operation was successful. +
+

RELATED INFORMATION

+

+Functions: +default_pager_backing_store_create, +default_pager_backing_store_delete. +

+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 @@ -

default_pager_object_create

Server Interface - Initialize a non-persistent memory object suitable for sharing between tasks.

SYNOPSIS

kern_return_t   default_pager_object_create
                (mach_port_t                              pager,
                 memory_object_t                 *memory_object,
                 vm_size_t                          object_size);


kern_return_t   seqnos_default_pager_object_create
                (mach_port_t                              pager,
                 mach_port_seqno_t                        seqno,
                 memory_object_t                 *memory_object,
                 vm_size_t                          object_size);

PARAMETERS

pager
[in default-pager (receive) right] The default memory manager service port.

seqno
[in scalar] The sequence number of this message relative to the pager port.

memory_object
[out memory-object send right] A memory object port (with full access) for the memory object.

object_size
[in scalar] The maximum size for the memory object.

DESCRIPTION

A default_pager_object_create 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 vm_map. This memory object has the same properties as does a memory object provided by vm_allocate: 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 memory_object_create 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: vm_map, host_default_memory_manager, memory_object_create, memory_object_default_server, seqnos_memory_object_default_server. \ No newline at end of file +

default_pager_object_create

+
+

+Server Interface - Initialize a non-persistent memory object suitable for sharing between tasks. +

SYNOPSIS

+
+kern_return_t   default_pager_object_create
+                (mach_port_t                              pager,
+                 memory_object_t                 *memory_object,
+                 vm_size_t                          object_size);
+
+
+kern_return_t   seqnos_default_pager_object_create
+                (mach_port_t                              pager,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_t                 *memory_object,
+                 vm_size_t                          object_size);
+
+

PARAMETERS

+
+

+

pager +
+[in default-pager (receive) right] +The default memory manager service +port. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the pager +port. +

+

memory_object +
+[out memory-object send right] +A memory object port (with full access) for the memory object. +

+

object_size +
+[in scalar] +The maximum size for the memory object. +
+

DESCRIPTION

+

+A default_pager_object_create 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 vm_map. This memory object has +the same properties as does a memory object provided by +vm_allocate: 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 memory_object_create 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +vm_map, +host_default_memory_manager, +memory_object_create, +memory_object_default_server, +seqnos_memory_object_default_server. 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 @@ -

device_read_overwrite_async

System Trap - Read a sequence of bytes from a device object into the caller's

SYNOPSIS

kern_return_t   device_read_overwrite_async
                (mach_port_t                             device,
                 mach_port_t                              queue,
                 mach_port_t                         request_id,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_len_t                      bytes_wanted,
                 io_buf_ptr_t                            buffer);

PARAMETERS

device
[in device send right] A device port to the device to be read.

queue
[in io_done queue send right] The port returned from the io_done_queue_create call.

request_id
[in send right] An unique request identifier that will be passed back as part of the io_done_result structure.

mode
[in scalar] I/O mode value. Meaningful options are:

D_NOWAIT
Do not wait if data is unavailable.

recnum
[in scalar] Record number to be read.

bytes_wanted
[in scalar] Size of data transfer.

buffer
[pointer to in array of bytes] Data buffer to be overwritten.

DESCRIPTION

The device_read_overwrite 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.

RETURN VALUES

device_read_overwrite_async returns only invalid parameter errors.

RELATED INFORMATION

Functions: device_read_async, device_read_async_inband, device_write_async, device_write_async_inband, io_done_queue_create. \ No newline at end of file +

device_read_overwrite_async

+
+

+System Trap - Read a sequence of bytes from a device object into the caller's +

SYNOPSIS

+
+kern_return_t   device_read_overwrite_async
+                (mach_port_t                             device,
+                 mach_port_t                              queue,
+                 mach_port_t                         request_id,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_len_t                      bytes_wanted,
+                 io_buf_ptr_t                            buffer);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] A device port to the device to be read. +

+

queue +
+[in io_done queue send right] The port returned from the +io_done_queue_create call. +

+

request_id +
+[in send right] An unique request identifier that will be passed back as +part of the io_done_result structure. +

+

mode +
+[in scalar] I/O mode value. Meaningful options are: +

+

+
D_NOWAIT +
+Do not wait if data is unavailable. +

+

+
recnum +
+[in scalar] Record number to be read. +

+

bytes_wanted +
+[in scalar] Size of data transfer. +

+

buffer +
+[pointer to in array of bytes] Data buffer to be overwritten. +
+

DESCRIPTION

+

+The device_read_overwrite 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. +

RETURN VALUES

+

+device_read_overwrite_async returns only invalid parameter errors. +

RELATED INFORMATION

+

+Functions: +device_read_async, +device_read_async_inband, +device_write_async, +device_write_async_inband, +io_done_queue_create. 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 @@ -

host_default_memory_manager

Function - Establish the official connection between the kernel and its default pager task.

SYNOPSIS

kern_return_t   host_default_memory_manager
                (host_priv_t                          host_priv,
                 mach_port_make_send_t          default_manager,
                 vm_size_t                         cluster_size);

PARAMETERS

host_priv
[in host-control send right] The control port naming the host for which the default memory manager is to be set.

default_manager
[pointer to in/out default-pager send right] A memory manager port to the new default memory manager. If this value is MACH_PORT_NULL, the old memory manager is not changed. The old memory manager port is returned in this variable.

cluster_size
[in scalar] The preferred cluster size (in bytes) for temporary memory objects.

DESCRIPTION

The host_default_memory_manager function establishes the default memory manager for a host. The named manager will be the target for future memory_object_create calls.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_create, vm_allocate. \ No newline at end of file +

host_default_memory_manager

+
+

+Function - Establish the official connection between the kernel and its default pager task. +

SYNOPSIS

+
+kern_return_t   host_default_memory_manager
+                (host_priv_t                          host_priv,
+                 mach_port_make_send_t          default_manager,
+                 vm_size_t                         cluster_size);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control send right] +The control port naming the host for which +the default memory manager is to be set. +

+

default_manager +
+[pointer to in/out default-pager send right] +A memory manager port to +the new default memory manager. If this value is MACH_PORT_NULL, +the old memory manager is not changed. The old memory +manager port is returned in this variable. +

+

cluster_size +
+[in scalar] +The preferred cluster size (in bytes) for temporary memory +objects. +
+

DESCRIPTION

+

+The host_default_memory_manager function establishes the default +memory manager for a host. The named manager will be the target for future +memory_object_create calls. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_create, +vm_allocate. 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 @@ -

memory_object_synchronize_completed

Function - Inform the kernel that synchronized data has been processed.

SYNOPSIS

kern_return_t   memory_object_synchronize_completed 
                (memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_offset_t                             length);

PARAMETERS

memory_control
[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 memory_object_init call.

offset
[in scalar] The offset within the memory object, in bytes.

length
[in scalar] The amount of data processed. The number must be an integral number of memory object pages.

DESCRIPTION

The memory_object_synchronize_completed function informs the kernel that previously synchronized data (memory_object_synchronize) has been queued or placed on backing storage. This reply causes the issuing client to return from its vm_msync call. The offset and length must match that of the corresponding memory_object_synchronize call. There may be multiple synchronize requests for a given memory object outstanding but they will not overlap.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_data_return, memory_object_synchronize, vm_msync. \ No newline at end of file +

memory_object_synchronize_completed

+
+

+Function - Inform the kernel that synchronized data has been processed. +

SYNOPSIS

+
+kern_return_t   memory_object_synchronize_completed 
+                (memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_offset_t                             length);
+
+

PARAMETERS

+
+

+

memory_control +
+[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 memory_object_init call. +

+

offset +
+[in scalar] +The offset within the memory object, in bytes. +

+

length +
+[in scalar] +The amount of data processed. The number must be an +integral number of memory object pages. +
+

DESCRIPTION

+

+The memory_object_synchronize_completed function informs the kernel +that previously synchronized data (memory_object_synchronize) +has been queued or placed on backing storage. This reply causes the issuing +client to return from its vm_msync call. The offset and length +must match that of the corresponding memory_object_synchronize +call. There may be multiple synchronize requests +for a given memory object outstanding but they will not overlap. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_data_return, +memory_object_synchronize, +vm_msync. 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 @@ -

memory_object_change_attributes

Function - Modify caller-specified subset of attributes representing target memory object.

SYNOPSIS

kern_return_t   memory_object_change_attributes
                (memory_object_control_t         memory_control,
                 memory_object_flavor_t                  flavor,
                 memory_object_info_t                attributes,
                 attributes                    attributes_count,
                 mach_port_t                           reply_to);

PARAMETERS

memory_control
[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 memory_object_init or memory_object_create call.

flavor
[in scalar] The type of information to be changed. Valid values are:

MEMORY_OBJECT_PERFORMANCE_INFO
Performance related attributes such as the cache indicator and the cluster size. attributes should specify a structure of type memory_object_perf_info.

MEMORY_OBJECT_BEHAVIOR_INFO
Behavior related attributes such as the copy strategy and sync invalidate flag. attributes should specify a structure of type memory_object_behavior_info.

MEMORY_OBJECT_ATTRIBUTES_INFO
Behavior and performance related attributes such as the copy strategy, cache indicator, and cluster size. attributes should specify a structure of type memory_object_attr_info.

attributes
[pointer to in structure] New attributes.

attributes_count
[in scalar] The size of the buffer (in natural-sized units).

reply_port
[in reply receive (to be converted to send) right] A port to which a reply (memory_object_change_completed) 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.

DESCRIPTION

The memory_object_change_attributes function sets various attributes of the specified memory object.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_change_completed, memory_object_get_attributes, memory_object_create.

Data Structures: memory_object_perf_info, memory_object_attr_info. \ No newline at end of file +

memory_object_change_attributes

+
+

+Function - Modify caller-specified subset of attributes representing target memory object. +

SYNOPSIS

+
+kern_return_t   memory_object_change_attributes
+                (memory_object_control_t         memory_control,
+                 memory_object_flavor_t                  flavor,
+                 memory_object_info_t                attributes,
+                 attributes                    attributes_count,
+                 mach_port_t                           reply_to);
+
+

PARAMETERS

+
+

+

memory_control +
+[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 memory_object_init + or memory_object_create call. +

+

flavor +
+[in scalar] +The type of information to be changed. Valid values are: +
+

+

MEMORY_OBJECT_PERFORMANCE_INFO +
+Performance related attributes such as the cache indicator and +the cluster size. attributes should specify a structure of type +memory_object_perf_info. +

+

MEMORY_OBJECT_BEHAVIOR_INFO +
+Behavior related attributes such as the copy strategy and sync +invalidate flag. attributes should specify a structure of type +memory_object_behavior_info. +

+

MEMORY_OBJECT_ATTRIBUTES_INFO +
+Behavior and performance related attributes such as the copy strategy, +cache indicator, and cluster size. attributes should specify a structure of type +memory_object_attr_info. +
+

+

attributes +
+[pointer to in structure] +New attributes. +

+

attributes_count +
+[in scalar] +The size of the buffer (in natural-sized units). +

+

reply_port +
+[in reply receive (to be converted to send) right] +A port to which a +reply (memory_object_change_completed) 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. +
+

DESCRIPTION

+

+The memory_object_change_attributes function sets various +attributes of the +specified memory object. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_change_completed, +memory_object_get_attributes, +memory_object_create. +

+Data Structures: +memory_object_perf_info, +memory_object_attr_info. + + 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 @@ -

memory_object_change_completed

Server Interface - Notify memory manager that kernel has updated memory object attributes as requested.

SYNOPSIS

kern_return_t   memory_object_change_completed
                (memory_object_t                     reply_port,
                 memory_object_control_t         memory_control,
                 memory_object_flavor_t                  flavor);


kern_return_t   seqnos_memory_object_change_completed
                (memory_object_t                     reply_port,
                 mach_port_seqno_t                        seqno,
                 memory_object_control_t         memory_control,
                 memory_object_flavor_t                  flavor);

PARAMETERS

reply_port
[in reply (receive) right] The port supplied in the corresponding memory_object_change_attributes call.

seqno
[in scalar] The sequence number of this message relative to the port named in the memory_object_change_attributes call.

memory_control
[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.

flavor
[in scalar] The flavor of attributes changed by the corresponding memory_object_change_attributes call.

DESCRIPTION

A memory_object_change_completed function is called as the result of a kernel message confirming the kernel's action in response to a memory_object_change_attributes call from the memory manager.

When the kernel completes the requested changes, it calls memory_object_change_completed (asynchronously) using the port explicitly provided in the memory_object_change_attributes call.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_change_attributes, memory_object_server, seqnos_memory_object_server. \ No newline at end of file +

memory_object_change_completed

+
+

+Server Interface - Notify memory manager that kernel has updated memory object attributes as requested. +

SYNOPSIS

+
+kern_return_t   memory_object_change_completed
+                (memory_object_t                     reply_port,
+                 memory_object_control_t         memory_control,
+                 memory_object_flavor_t                  flavor);
+
+
+kern_return_t   seqnos_memory_object_change_completed
+                (memory_object_t                     reply_port,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_control_t         memory_control,
+                 memory_object_flavor_t                  flavor);
+
+

PARAMETERS

+
+

+

reply_port +
+[in reply (receive) right] +The port supplied in the corresponding +memory_object_change_attributes call. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the port +named in the memory_object_change_attributes call. +

+

memory_control +
+[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. +

+

flavor +
+[in scalar] +The flavor of attributes changed by the corresponding +memory_object_change_attributes call. +
+

DESCRIPTION

+

+A memory_object_change_completed function is called +as the result of a +kernel message confirming the kernel's action in response to a +memory_object_change_attributes call from the memory manager. +

+When the kernel completes the requested changes, it calls +memory_object_change_completed (asynchronously) using +the port explicitly provided in +the memory_object_change_attributes call. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_change_attributes, +memory_object_server, +seqnos_memory_object_server. 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 @@ -

memory_object_data_initialize

Server Interface - Request that the default pager record initialization information for specified memory object.

SYNOPSIS

kern_return_t   memory_object_data_initialize
                (memory_object_t                  memory_object,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 pointer_t                                 data);


kern_return_t   seqnos_memory_object_data_initialize
                (memory_object_t                  memory_object,
                 mach_port_seqno_t                        seqno,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 pointer_t                                 data);

PARAMETERS

memory_object
[in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data, as supplied by the kernel in a memory_object_create call.

seqno
[in scalar] The sequence number of this message relative to the abstract memory object port.

memory_control
[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.

offset
[in scalar] The offset within the memory object.

data
[in pointer to dynamic array of bytes] The data that has been modified while cached in physical memory.

DESCRIPTION

A memory_object_data_initialize 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 memory_object_data_initialize or memory_object_data_return), it should ignore this call. Otherwise, the call behaves the same as the memory_object_data_return call.

The kernel makes this call only to the default memory manager and only on temporary memory objects that it has created with memory_object_create.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_create, memory_object_data_return, memory_object_default_server, seqnos_memory_object_default_server. \ No newline at end of file +

memory_object_data_initialize

+
+

+Server Interface - Request that the default pager record initialization information for specified memory object. +

SYNOPSIS

+
+kern_return_t   memory_object_data_initialize
+                (memory_object_t                  memory_object,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 pointer_t                                 data);
+
+
+kern_return_t   seqnos_memory_object_data_initialize
+                (memory_object_t                  memory_object,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 pointer_t                                 data);
+
+

PARAMETERS

+
+

+

memory_object +
+[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data, as supplied by the +kernel in a memory_object_create call. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the abstract +memory object port. +

+

memory_control +
+[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. +

+

offset +
+[in scalar] +The offset within the memory object. +

+

data +
+[in pointer to dynamic array of bytes] +The data that has been modified +while cached in physical memory. +
+

DESCRIPTION

+

+A memory_object_data_initialize 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 memory_object_data_initialize or +memory_object_data_return), it +should ignore this call. Otherwise, the call behaves the same as the +memory_object_data_return call. +

+The kernel makes this call only to the default memory manager and only on +temporary memory objects that it has created with +memory_object_create. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_create, +memory_object_data_return, +memory_object_default_server, +seqnos_memory_object_default_server. 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 @@ -

memory_object_data_unavailable

Function - Instruct kernel to zero-fill pages as requested data does not exist.

SYNOPSIS

kern_return_t   memory_object_data_unavailable
                (memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                                 size);

PARAMETERS

memory_control
[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 memory_object_init or a memory_object_create call.

offset
[in scalar] The offset within the memory object, in bytes.

size
[in scalar] The number of bytes of data (starting at offset). The number must convert to an integral number of memory object pages.

DESCRIPTION

The memory_object_data_unavailable 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.

A memory manager can use this call in any of the following situations:

  • When the object was created by the kernel (via memory_object_create) and the kernel has not yet provided data for the region (via either memory_object_data_initialize or memory_object_data_return). 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.

  • When the object is a normal user-created memory object. In this case, the kernel should provide zero-filled pages for the region.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_create, memory_object_data_error, memory_object_data_request, memory_object_data_supply. \ No newline at end of file +

memory_object_data_unavailable

+
+

+Function - Instruct kernel to zero-fill pages as requested data does not exist. +

SYNOPSIS

+
+kern_return_t   memory_object_data_unavailable
+                (memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                                 size);
+
+

PARAMETERS

+
+

+

memory_control +
+[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 memory_object_init or a +memory_object_create call. +

+

offset +
+[in scalar] +The offset within the memory object, in bytes. +

+

size +
+[in scalar] +The number of bytes of data (starting at offset). The number +must convert to an integral number of memory object pages. +
+

DESCRIPTION

+

+The memory_object_data_unavailable 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. +

+A memory manager can use this call in any of the following situations: +

    +
  • +When the object was created by the kernel +(via memory_object_create) and +the kernel has not yet provided data for the region (via either +memory_object_data_initialize or memory_object_data_return). +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. +

    +

  • +When the object is a normal user-created memory object. In this case, the +kernel should provide zero-filled pages for the region. +
+

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_create, +memory_object_data_error, +memory_object_data_request, +memory_object_data_supply. 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 @@ -

memory_object_default_server

Function - Handle kernel operation request targeted for the default pager.

SYNOPSIS

boolean_t	memory_object_default_server
		(mach_msg_header_t	request_msg,
		mach_msg_header_t	reply_ms);

PARAMETERS

in_msg
[pointer to in structure] The memory manager message received from the kernel.

out_msg
[out structure] A reply message. Note that no kernel messages to a memory manager expect a direct reply.

DESCRIPTION

The memory_object_default_server 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 memory_object_server.

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 memory_object_default_server function performs all necessary argument handling for a kernel message and calls one of the default memory manager functions.

RETURN VALUES

TRUE
The message was handled and the appropriate function was called.

FALSE
The message did not apply to this memory management interface and no other action was taken.

RELATED INFORMATION

Functions: seqnos_memory_object_default_server, memory_object_server, memory_object_create, memory_object_data_initialize, default_pager_object_create, default_pager_info. \ No newline at end of file +

memory_object_default_server

+
+

+Function - Handle kernel operation request targeted for the default pager. +

SYNOPSIS

+
+boolean_t	memory_object_default_server
+		(mach_msg_header_t	request_msg,
+		mach_msg_header_t	reply_ms);
+
+

PARAMETERS

+
+

+

in_msg +
+[pointer to in structure] +The memory manager message received from +the kernel. +

+

out_msg +
+[out structure] +A reply message. Note that no kernel messages to a +memory manager expect a direct reply. +
+

DESCRIPTION

+

+The memory_object_default_server 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 memory_object_server. +

+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 +memory_object_default_server function performs all necessary argument +handling for a kernel message and calls one of the default memory manager +functions. +

RETURN VALUES

+
+

+

TRUE +
+The message was handled and the appropriate function was called. +

+

FALSE +
+The message did not apply to this memory management interface and +no other action was taken. +
+

RELATED INFORMATION

+

+Functions: +seqnos_memory_object_default_server, +memory_object_server, +memory_object_create, +memory_object_data_initialize, +default_pager_object_create, +default_pager_info. + 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 @@ -

memory_object_get_attributes

Function - Return current attributes for a memory object.

SYNOPSIS

kern_return_t   memory_object_get_attributes
                (memory_object_control_t         memory_control,
                 memory_object_flavor_t                  flavor,
                 memory_object_info_t                attributes,
                 mach_msg_type_number_t        attributes_count);

PARAMETERS

memory_control
[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 memory_object_notify call.

flavor
[in scalar] The type of information to be returned. Valid values are:

MEMORY_OBJECT_PERFORMANCE_INFO
Performance related attributes such as the cache indicator and the cluster size. attributes should specify a structure of type memory_object_perf_info.

MEMORY_OBJECT_BEHAVIOR_INFO
Behavior related attributes such as the copy strategy and sync invalidate flag. attributes should specify a structure of type memory_object_behavior_info.
MEMORY_OBJECT_ATTRIBUTES_INFO
Behavior and performance related attributes such as the copy strategy, cache indicator, and cluster size. attributes should specify a structure of type memory_object_attr_info.

attributes
[out structure] Current attributes.

attributes_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The memory_object_get_attributes function retrieves the current attributes for the specified memory object.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_change_attributes.

Data Structures: memory_object_perf_info, memory_object_attr_info. \ No newline at end of file +

memory_object_get_attributes

+
+

+Function - Return current attributes for a memory object. +

SYNOPSIS

+
+kern_return_t   memory_object_get_attributes
+                (memory_object_control_t         memory_control,
+                 memory_object_flavor_t                  flavor,
+                 memory_object_info_t                attributes,
+                 mach_msg_type_number_t        attributes_count);
+
+

PARAMETERS

+
+

+

memory_control +
+[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 memory_object_notify call. +

+

flavor +
+[in scalar] +The type of information to be returned. Valid values are: +
+

+

MEMORY_OBJECT_PERFORMANCE_INFO +
+Performance related attributes such as the cache indicator and +the cluster size. attributes should specify a structure of type +memory_object_perf_info. +

+

MEMORY_OBJECT_BEHAVIOR_INFO +
+Behavior related attributes such as the copy strategy and sync +invalidate flag. attributes should specify a structure of type +memory_object_behavior_info. +
MEMORY_OBJECT_ATTRIBUTES_INFO +
+Behavior and performance related attributes such as the copy strategy, +cache indicator, and cluster size. attributes should specify a structure of type +memory_object_attr_info. +
+

+

attributes +
+[out structure] +Current attributes. +

+

attributes_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The memory_object_get_attributes function retrieves +the current attributes for +the specified memory object. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_change_attributes. +

+Data Structures: +memory_object_perf_info, +memory_object_attr_info. 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 @@ -

memory_object_lock_completed

Server Interface - Report to memory manager that a previous consistency control request has been handled.

SYNOPSIS

kern_return_t   memory_object_lock_completed
                (memory_object_t                     reply_port,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                               length);


kern_return_t   seqnos_memory_object_lock_completed
                (memory_object_t                     reply_port,
                 mach_port_seqno_t                        seqno,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                               length);

PARAMETERS

reply_port
[in reply (receive) right] The port supplied in the corresponding memory_object_lock_request call.

seqno
[in scalar] The sequence number of this message relative to the port named in the memory_object_lock_completed message.

memory_control
[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.

offset
[in scalar] The offset within the memory object.

length
[in scalar] The number of bytes to which the call refers, starting at offset. The number converts to an integral number of memory object pages.

DESCRIPTION

A memory_object_lock_completed function is called as the result of a kernel message confirming the kernel's action in response to a memory_object_lock_request call from the memory manager. The memory manager can use the memory_object_lock_request call to:

  • Alter access restrictions specified in the memory_object_data_supply call or a previous memory_object_lock_request call.

  • Write back modifications made in memory.

  • Invalidate its cached data.

When the kernel completes the requested actions, it calls memory_object_lock_completed (asynchronously) using the port explicitly provided in the memory_object_lock_request 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 memory_object_lock_request call. Receiving the memory_object_lock_completed 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_lock_request, memory_object_server, seqnos_memory_object_server. \ No newline at end of file +

memory_object_lock_completed

+
+

+Server Interface - Report to memory manager that a previous consistency control request has been handled. +

SYNOPSIS

+
+kern_return_t   memory_object_lock_completed
+                (memory_object_t                     reply_port,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                               length);
+
+
+kern_return_t   seqnos_memory_object_lock_completed
+                (memory_object_t                     reply_port,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                               length);
+
+

PARAMETERS

+
+

+

reply_port +
+[in reply (receive) right] +The port supplied in the corresponding +memory_object_lock_request call. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the port +named in the memory_object_lock_completed message. +

+

memory_control +
+[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. +

+

offset +
+[in scalar] +The offset within the memory object. +

+

length +
+[in scalar] +The number of bytes to which the call refers, starting at +offset. The number converts to an integral number of memory object +pages. +
+

DESCRIPTION

+

+A memory_object_lock_completed function is called as +the result of a kernel +message confirming the kernel's action in response to a +memory_object_lock_request call from the memory manager. +The memory manager can use the memory_object_lock_request call to: +

    +
  • +Alter access restrictions specified in the memory_object_data_supply +call or a previous memory_object_lock_request call. +

    +

  • +Write back modifications made in memory. +

    +

  • +Invalidate its cached data. +
+

+When the kernel completes the requested actions, it calls +memory_object_lock_completed (asynchronously) using +the port explicitly provided in the +memory_object_lock_request 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 +memory_object_lock_request call. Receiving the +memory_object_lock_completed 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_lock_request, +memory_object_server, +seqnos_memory_object_server. 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 @@ -

memory_object_supply_completed

Server Interface - Return results associated with the kernel's handling of a particular memory manager request.

SYNOPSIS

kern_return_t   memory_object_supply_completed
                (memory_object_t                     reply_port,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                               length,
                 kern_return_t                           result,
                 vm_offset_t                       error_offset);


kern_return_t   seqnos_memory_object_supply_completed
                (memory_object_t                     reply_port,
                 mach_port_seqno_t                        seqno,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                               length,
                 kern_return_t                           result,
                 vm_offset_t                       error_offset);

PARAMETERS

reply_port
[in reply (receive) right] The port supplied in the corresponding memory_object_data_supply call.

seqno
[in scalar] The sequence number of this message relative to the port named in the memory_object_data_supply call.

memory_control
[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.

offset
[in scalar] The offset within the memory object from the corresponding data supply call.

length
[in scalar] The number of bytes accepted. The number converts to an integral number of memory object pages.

result
[in scalar] A kernel return code indicating the result of the supply operation, possibly KERN_SUCCESS. KERN_MEMORY_PRESENT is currently the only error returned; other errors (invalid arguments, for example) abort the data supply operation.

error_offset
[in scalar] The offset within the memory object where the first error occurred.

DESCRIPTION

A memory_object_supply_completed function is called as the result of a kernel message confirming the kernel's action in response to a memory_object_data_supply call from the memory manager.

When the kernel accepts the pages, it calls memory_object_supply_completed (asynchronously) using the port explicitly provided in the memory_object_data_supply 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 memory_object_data_return 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_data_supply, memory_object_server, seqnos_memory_object_server. \ No newline at end of file +

memory_object_supply_completed

+
+

+Server Interface - Return results associated with the kernel's handling of a particular memory manager request. +

SYNOPSIS

+
+kern_return_t   memory_object_supply_completed
+                (memory_object_t                     reply_port,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                               length,
+                 kern_return_t                           result,
+                 vm_offset_t                       error_offset);
+
+
+kern_return_t   seqnos_memory_object_supply_completed
+                (memory_object_t                     reply_port,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                               length,
+                 kern_return_t                           result,
+                 vm_offset_t                       error_offset);
+
+

PARAMETERS

+
+

+

reply_port +
+[in reply (receive) right] +The port supplied in the corresponding +memory_object_data_supply call. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the port +named in the memory_object_data_supply call. +

+

memory_control +
+[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. +

+

offset +
+[in scalar] +The offset within the memory object from the corresponding +data supply call. +

+

length +
+[in scalar] +The number of bytes accepted. The number converts to an +integral number of memory object pages. +

+

result +
+[in scalar] +A kernel return code indicating the result of the supply +operation, possibly KERN_SUCCESS. KERN_MEMORY_PRESENT is +currently the only error returned; other errors (invalid arguments, for +example) abort the data supply operation. +

+

error_offset +
+[in scalar] +The offset within the memory object where the first error +occurred. +
+

DESCRIPTION

+

+A memory_object_supply_completed function is called +as the result of a +kernel message confirming the kernel's action in response to a +memory_object_data_supply call from the memory manager. +

+When the kernel accepts the pages, it calls +memory_object_supply_completed +(asynchronously) using the port explicitly provided in the +memory_object_data_supply 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 memory_object_data_return +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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_data_supply, +memory_object_server, +seqnos_memory_object_server. 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 @@ -

mach_port_allocate_subsystem

Function - Create a port right associated with the caller-specified subsystem.

SYNOPSIS

kern_return_t   mach_port_allocate_subsystem
                (ipc_space_t                               task,
                 subsystem_t                             subsys,
                 mach_port_name_t              mach_port_name_t);

PARAMETERS

task
[in task send right] The task acquiring the port right.

subsys
[in scalar] The port right naming the subsystem the newly created port is to be associated with.

name
[out scalar] The task's name for the port right. This can be any name that wasn't in use.

DESCRIPTION

The mach_port_allocate_subsystem function creates a new right and associates it with the specifed subsystem (specified via the subsys parameter) previously registered via a call to the mach_subsystem_create interface. The new right's name is returned in the name parameter. The association of this port with the subsystem is immutable for the life of the port.

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.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_SUCCESS
The right is allocated.

KERN_INVALID_TASK
The space is null.

KERN_INVALID_TASK
The space is dead.

KERN_RESOURCE_SHORTAGE
Couldn't allocate memory.

KERN_NO_SPACE
No room in space for another right.

RELATED INFORMATION

Functions: mach_subsystem_create, thread_activation_create. \ No newline at end of file +

mach_port_allocate_subsystem

+
+

+Function - Create a port right associated with the caller-specified subsystem. +

SYNOPSIS

+
+kern_return_t   mach_port_allocate_subsystem
+                (ipc_space_t                               task,
+                 subsystem_t                             subsys,
+                 mach_port_name_t              mach_port_name_t);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] The task acquiring the port right. +

+

subsys +
+[in scalar] The port right naming the subsystem the newly created port +is to be associated with. +

+

name +
+[out scalar] The task's name for the port right. This can be any name +that wasn't in use. +
+

DESCRIPTION

+

+The mach_port_allocate_subsystem function creates a new right +and associates it +with the specifed subsystem (specified via the subsys parameter) +previously registered via a call to the +mach_subsystem_create interface. +The new right's name is returned in the name parameter. The +association of this port with the subsystem is immutable for the +life of the port. +

+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. +

NOTES

+

+This interface is machine word length specific because of the port +name parameter. +

RETURN VALUES

+
+

+

KERN_SUCCESS +
+The right is allocated. +

+

KERN_INVALID_TASK +
+The space is null. +

+

KERN_INVALID_TASK +
+The space is dead. +

+

KERN_RESOURCE_SHORTAGE +
+Couldn't allocate memory. +

+

KERN_NO_SPACE +
+No room in space for another right. +
+

RELATED INFORMATION

+

+Functions: +mach_subsystem_create, +thread_activation_create. 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 @@ -

mach_port_request_notification

Function - Request notification of the specified port event type.

SYNOPSIS

kern_return_t   mach_port_request_notification
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_msg_id_t                          variant,
                 mach_port_mscount_t                       sync,
                 mach_port_send_once_t                   notify,
                 mach_msg_type_name_t               notify_type,
                 mach_port_send_once_t                *previous);

PARAMETERS

task
[in task send right] The task holding the specified right.

name
[in scalar] The task's name for the right.

variant
[in scalar] The type of notification.

sync
[in scalar] Some variants use this value to overcome race conditions.

notify
[in notify send-once or receive (to be converted to send-once) right] A send-once right, to which the notification will be sent.

notify_type
[in scalar] IPC type of the notify right; either MACH_MSG_TYPE_MAKE_SEND_ONCE or MACH_MSG_TYPE_MOVE_SEND_ONCE.

previous
[out notify send-once right] The previously registered send-once right.

DESCRIPTION

The mach_port_request_notification 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 MACH_PORT_NULL for none). A notification request may be cancelled by providing MACH_PORT_NULL.

The variant argument takes the following values:

MACH_NOTIFY_PORT_DESTROYED
sync must be zero. The name 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 mach_port_destroy, then instead the receive right will be sent in a port-destroyed notification to the registered send-once right.

MACH_NOTIFY_DEAD_NAME
The call requests a dead-name notification. name 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 sync is non-zero, the name may specify a dead name, and a dead-name notification is immediately generated.

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.

If the name is made available for reuse, perhaps because of mach_port_destroy or mach_port_mod_refs, 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.

MACH_NOTIFY_NO_SENDERS
The call requests a no-senders notification. name 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.

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.

When moving a receive right, no-senders notifications are canceled, with a send-once notification sent to indicate the cancelation.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
name did not denote a right.

KERN_INVALID_RIGHT
name denoted an invalid right.

KERN_INVALID_CAPABILITY
notify was invalid.

When using MACH_NOTIFY_DEAD_NAME:

KERN_UREFS_OVERFLOW
name denotes a dead name, but generating an immediate dead-name notification would overflow the name's user-reference count.

RELATED INFORMATION

Functions: mach_msg, mach_port_get_attributes. \ No newline at end of file +

mach_port_request_notification

+
+

+Function - Request notification of the specified port event type. +

SYNOPSIS

+
+kern_return_t   mach_port_request_notification
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_msg_id_t                          variant,
+                 mach_port_mscount_t                       sync,
+                 mach_port_send_once_t                   notify,
+                 mach_msg_type_name_t               notify_type,
+                 mach_port_send_once_t                *previous);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task holding the specified right. +

+

name +
+[in scalar] +The task's name for the right. +

+

variant +
+[in scalar] +The type of notification. +

+

sync +
+[in scalar] +Some variants use this value to overcome race conditions. +

+

notify +
+[in notify send-once or receive (to be converted to send-once) right] +A +send-once right, to which the notification will be sent. +

+

notify_type +
+[in scalar] +IPC type of the notify right; either +MACH_MSG_TYPE_MAKE_SEND_ONCE or MACH_MSG_TYPE_MOVE_SEND_ONCE. +

+

previous +
+[out notify send-once right] +The previously registered send-once right. +
+

DESCRIPTION

+

+The mach_port_request_notification 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 +MACH_PORT_NULL for none). A notification request may be +cancelled by providing MACH_PORT_NULL. +

+The variant argument takes the following values: +

+
MACH_NOTIFY_PORT_DESTROYED +
+sync must be zero. The name 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 mach_port_destroy, then instead the receive right will be +sent in a port-destroyed notification to the registered send-once right. +

+

MACH_NOTIFY_DEAD_NAME +
+The call requests a dead-name notification. name 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 sync is non-zero, +the name may specify a dead name, and +a dead-name notification is immediately generated. +

+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. +

+If the name is made available for reuse, perhaps because of +mach_port_destroy or mach_port_mod_refs, +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. +

+

MACH_NOTIFY_NO_SENDERS +
+The call requests a no-senders notification. name 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. +

+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. +

+When moving a receive right, no-senders notifications are canceled, +with a send-once notification sent to indicate the cancelation. +

+

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+name did not denote a right. +

+

KERN_INVALID_RIGHT +
+name denoted an invalid right. +

+

KERN_INVALID_CAPABILITY +
+notify was invalid. +
+

+When using MACH_NOTIFY_DEAD_NAME: +

+

+

KERN_UREFS_OVERFLOW +
+name denotes a dead name, but generating an immediate dead-name +notification would overflow the name's user-reference count. +
+

RELATED INFORMATION

+

+Functions: +mach_msg, +mach_port_get_attributes. 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 @@ -

processor_set_policy_control

Function - Set target processor set's scheduling policy state.

SYNOPSIS

kern_return_t	processor_set_policy_control
		(processor_set_t	processor_set_control,
		processor_set_flavor_t	flavor,
		processor_set_info_t	policy_info,
		mach_msg_type_number_t*	policy_info_count,
		boolean_t	change_tasks_threads);

PARAMETERS

processor_set_control
[in processor-set-control send right] A processor set control port.
flavor
[in scalar] The type of policy change to make.
PROCESSOR_SET_TIMESHARE_DEFAULT
Change the base attributes for the timeshare scheduling policy, making timeshare the default policy. The structure is policy_timeshare_base.
PROCESSOR_SET_FIFO_DEFAULT
Change the base attributes for the FIFO (first-in, first-out) scheduling policy, making FIFO the default policy. The structure is policy_fifo_base.
PROCESSOR_SET_RR_DEFAULT
Changed the base attributes for the round-robin scheduling policy, making round robin the default policy. The structure is policy_rr_base.
PROCESSOR_SET_TIMESHARE_LIMITS
Change the limits on the allowed timeshare policy attributes. The structure is defined by policy_timeshare_limit.
PROCESSOR_SET_RR_LIMITS
Change the limits on the allowed round robin policy attributes. The structure is defined by policy_rr_limit.
PROCESSOR_SET_FIFO_LIMITS
Change the limits on the allowed first-in, first-out policy attributes. The structure is defined by policy_fifo_limit.
PROCESSOR_SET_ENABLED_POLICIES
Change the set of enabled policies. The data is a bit-vector.
policy_info
[in structure] The relevant policy information.
policy_info_count
[in scalar] The size of the buffer (in natural-sized units).
change_tasks_threads
[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.

DESCRIPTION

The processor_set_policy_control function controls scheduling attributes governing the processor set.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_set_statistics, processor_set_create, processor_set_default, processor_assign, processor_set_info.

Data Structures: policy_timeshare_info, policy_rr_info, policy_fifo_info. \ No newline at end of file +

processor_set_policy_control

+
+

+Function - Set target processor set's scheduling policy state. +

SYNOPSIS

+
+kern_return_t	processor_set_policy_control
+		(processor_set_t	processor_set_control,
+		processor_set_flavor_t	flavor,
+		processor_set_info_t	policy_info,
+		mach_msg_type_number_t*	policy_info_count,
+		boolean_t	change_tasks_threads);
+
+

PARAMETERS

+
+
processor_set_control +
+[in processor-set-control send right] +A processor set control port. +
flavor +
+[in scalar] +The type of policy change to make. +
+
PROCESSOR_SET_TIMESHARE_DEFAULT +
+Change the base attributes for the timeshare scheduling +policy, making timeshare the default policy. The structure is +policy_timeshare_base. +
PROCESSOR_SET_FIFO_DEFAULT +
+Change the base attributes for the FIFO (first-in, first-out) +scheduling policy, making FIFO the default policy. The +structure is policy_fifo_base. +
PROCESSOR_SET_RR_DEFAULT +
+Changed the base attributes for the round-robin scheduling +policy, making round robin the default policy. The structure is +policy_rr_base. +
PROCESSOR_SET_TIMESHARE_LIMITS +
+Change the limits on the allowed timeshare policy attributes. +The structure is defined by policy_timeshare_limit. +
PROCESSOR_SET_RR_LIMITS +
+Change the limits on the allowed round robin policy +attributes. The structure is defined by policy_rr_limit. +
PROCESSOR_SET_FIFO_LIMITS +
+Change the limits on the allowed first-in, first-out policy +attributes. The structure is defined by policy_fifo_limit. +
PROCESSOR_SET_ENABLED_POLICIES +
+Change the set of enabled policies. The data is a bit-vector. +
+
policy_info +
+[in structure] +The relevant policy information. +
policy_info_count +
+[in scalar] +The size of the buffer (in natural-sized units). +
change_tasks_threads +
+[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. +
+

DESCRIPTION

+

+The processor_set_policy_control function controls +scheduling attributes governing the processor set. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_set_statistics, +processor_set_create, +processor_set_default, +processor_assign, +processor_set_info. +

+Data Structures: +policy_timeshare_info, +policy_rr_info, +policy_fifo_info. 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 @@ -

processor_set_policy_disable

Function - Disables a scheduling policy for a processor set.

SYNOPSIS

#include< mach/mach_host.h>

kern_return_t	processor_set_policy_disable
		(processor_set_t	processor_set,
		int	policy,
		boolean_t	change_threads);

PARAMETERS

processor_set
[in processor-set-control port] The control port for the processor set for which a scheduling policy is to be disabled.
policy
[in scalar] Policy to be disabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI.
change_threads
[in scalar] If true, causes the scheduling policy for all threads currently running with policy to POLICY_TIMESHARE.

DESCRIPTION

The processor_set_policy_disable function restricts the set of scheduling policies allowed for processor_set. 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 processor_set_info. Timesharing may not be forbidden for any processor set. This is a compromise to reduce the complexity of the assign operation; any thread whose policy is forbidden by its target processor set has its policy reset to timesharing. Disabling a scheduling policy for a processor set has no effect on threads currently assigned to that processor set unless change_threads is TRUE, in which case their policies will be reset to timesharing.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_set_policy_enable, processor_set_info, thread_policy. \ No newline at end of file +

processor_set_policy_disable

+
+

+Function - Disables a scheduling policy for a processor set. +

SYNOPSIS

+
+#include< mach/mach_host.h>
+
+kern_return_t	processor_set_policy_disable
+		(processor_set_t	processor_set,
+		int	policy,
+		boolean_t	change_threads);
+
+

PARAMETERS

+
+
processor_set +
+[in processor-set-control port] The control port for the processor set for which a scheduling policy is to be disabled. +
policy +
+[in scalar] Policy to be disabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI. +
change_threads +
+[in scalar] If true, causes the scheduling policy for all threads currently running with policy to POLICY_TIMESHARE. +
+

DESCRIPTION

+

+The processor_set_policy_disable +function restricts the set of scheduling policies allowed for +processor_set. 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 processor_set_info. Timesharing may +not be forbidden for any processor set. This is a compromise to reduce +the complexity of the assign operation; any thread whose +policy is forbidden by its target processor set has its +policy reset to timesharing. Disabling a scheduling +policy for a processor set has no effect on threads +currently assigned to that processor set unless +change_threads is TRUE, in which case their policies will +be reset to timesharing. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_set_policy_enable, +processor_set_info, +thread_policy. 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 @@ -

processor_set_policy_enable

Function - Enables a scheduling policy for a processor set.

SYNOPSIS

#include< mach/mach_host.h>

kern_return_t	processor_set_policy_enable
		(processor_set_t	processor_set,
		int	policy);

PARAMETERS

processor_set
[in processor-set-control port] The control port for the processor set for which a scheduling policy is to be enabled.
policy
[in scalar] Policy to be enabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI.

DESCRIPTION

The processor_set_policy_enable function extends the set of scheduling policies allowed for processor_set. 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 processor_set_info.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_set_info, processor_set_policy_disable, thread_policy. \ No newline at end of file +

processor_set_policy_enable

+
+

+Function - Enables a scheduling policy for a processor set. +

SYNOPSIS

+
+#include< mach/mach_host.h>
+
+kern_return_t	processor_set_policy_enable
+		(processor_set_t	processor_set,
+		int	policy);
+
+

PARAMETERS

+
+
processor_set +
+[in processor-set-control port] The control port for the processor set for which a scheduling policy is to be enabled. +
policy +
+[in scalar] Policy to be enabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI. +
+

DESCRIPTION

+

+The processor_set_policy_enable +function extends the set of scheduling policies allowed for +processor_set. 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 processor_set_info. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_set_info, +processor_set_policy_disable, +thread_policy. 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 @@ -

seqnos_memory_object_default_server

Function - Handle kernel operation request targeted for the default pager.

SYNOPSIS

boolean_t	seqnos_memory_object_default_server
		(mach_msg_header_t	request_msg,
		mach_msg_header_t	reply_ms);

PARAMETERS

in_msg
[pointer to in structure] The memory manager message received from the kernel.

out_msg
[out structure] A reply message. Note that no kernel messages to a memory manager expect a direct reply.

DESCRIPTION

The seqnos_memory_object_default_server 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 seqnos_memory_object_server.

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 seqnos_memory_object_default_server function performs all necessary argument handling for a kernel message and calls one of the default memory manager functions.

NOTES

seqnos_memory_object_default_server differs from memory_object_default_server in that it supplies message sequence numbers to the server interfaces it calls.

RETURN VALUES

TRUE
The message was handled and the appropriate function was called.

FALSE
The message did not apply to this memory management interface and no other action was taken.

RELATED INFORMATION

Functions: memory_object_default_server, seqnos_memory_object_server, seqnos_memory_object_create, seqnos_memory_object_data_initialize, seqnos_default_pager_object_create, seqnos_default_pager_info. \ No newline at end of file +

seqnos_memory_object_default_server

+
+

+Function - Handle kernel operation request targeted for the default pager. +

SYNOPSIS

+
+boolean_t	seqnos_memory_object_default_server
+		(mach_msg_header_t	request_msg,
+		mach_msg_header_t	reply_ms);
+
+

PARAMETERS

+
+

+

in_msg +
+[pointer to in structure] +The memory manager message received from +the kernel. +

+

out_msg +
+[out structure] +A reply message. Note that no kernel messages to a +memory manager expect a direct reply. +
+

DESCRIPTION

+

+The seqnos_memory_object_default_server 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 seqnos_memory_object_server. +

+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 +seqnos_memory_object_default_server function performs all necessary +argument handling for a kernel message and calls one of the default memory +manager functions. +

NOTES

+

+seqnos_memory_object_default_server differs from +memory_object_default_server in that it supplies message +sequence numbers to the server +interfaces it calls. +

RETURN VALUES

+
+

+

TRUE +
+The message was handled and the appropriate function was called. +

+

FALSE +
+The message did not apply to this memory management interface and +no other action was taken. +
+

RELATED INFORMATION

+

+Functions: +memory_object_default_server, +seqnos_memory_object_server, +seqnos_memory_object_create, +seqnos_memory_object_data_initialize, +seqnos_default_pager_object_create, +seqnos_default_pager_info. 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 @@ -

seqnos_memory_object_server

Function - Handle kernel operation request aimed at a given memory manager.

SYNOPSIS

boolean_t	seqnos_memory_object_server
		(mach_msg_header_t	request_msg,
		mach_msg_header_t	reply_ms);

PARAMETERS

in_msg
[pointer to in structure] The memory manager message received from the kernel.

out_msg
[out structure] A reply message. No messages to a memory manager expect a direct reply, so this field is not used.

DESCRIPTION

The seqnos_memory_object_server function is the MIG generated server handling function to handle messages from the kernel targeted to a memory manager.

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 seqnos_memory_object_server function performs all necessary argument handling for a kernel message and calls one of the memory manager functions to interpret the message.

NOTES

seqnos_memory_object_server differs from memory_object_server in that it supplies message sequence numbers to the server interfaces.

RETURN VALUES

TRUE
The message was handled and the appropriate function was called.

FALSE
The message did not apply to this memory management interface and no other action was taken.

RELATED INFORMATION

Functions: seqnos_memory_object_default_server, seqnos_memory_object_data_request, seqnos_memory_object_data_unlock, seqnos_memory_object_data_return, seqnos_memory_object_supply_completed, seqnos_memory_object_lock_completed, seqnos_seqnos_memory_object_change_completed, seqnos_memory_object_terminate, seqnos_memory_object_synchronize, memory_object_server. \ No newline at end of file +

seqnos_memory_object_server

+
+

+Function - Handle kernel operation request aimed at a given memory manager. +

SYNOPSIS

+
+boolean_t	seqnos_memory_object_server
+		(mach_msg_header_t	request_msg,
+		mach_msg_header_t	reply_ms);
+
+

PARAMETERS

+
+

+

in_msg +
+[pointer to in structure] +The memory manager message received from +the kernel. +

+

out_msg +
+[out structure] +A reply message. No messages to a memory manager +expect a direct reply, so this field is not used. +
+

DESCRIPTION

+

+The seqnos_memory_object_server function is the MIG generated server +handling function to handle messages from the kernel targeted to a memory +manager. +

+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 +seqnos_memory_object_server function performs all necessary argument +handling for a kernel message and calls one of the memory manager functions to +interpret the message. +

NOTES

+

+seqnos_memory_object_server differs from memory_object_server +in that it +supplies message sequence numbers to the server interfaces. +

RETURN VALUES

+
+

+

TRUE +
+The message was handled and the appropriate function was called. +

+

FALSE +
+The message did not apply to this memory management interface and +no other action was taken. +
+

RELATED INFORMATION

+

+Functions: +seqnos_memory_object_default_server, +seqnos_memory_object_data_request, +seqnos_memory_object_data_unlock, +seqnos_memory_object_data_return, +seqnos_memory_object_supply_completed, +seqnos_memory_object_lock_completed, +seqnos_seqnos_memory_object_change_completed, +seqnos_memory_object_terminate, +seqnos_memory_object_synchronize, +memory_object_server. 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 @@ -

thread_swap_exception_ports

Function - Swap exception ports for a thread.

SYNOPSIS

kern_return_t   thread_swap_exception_ports
                (thread_act_t                            thread,
                 exception_mask_t               exception_types,
                 mach_port_t                     exception_port,
                 exception_behavior_t                  behavior,
                 thread_state_flavor_t                   flavor,
                 exception_mask_array_t     old_exception_masks,
                 old_exception_masks        old_exception_count,
                 exception_port_array_t     old_exception_ports,
                 exception_behavior_array_t       old_behaviors,
                 exception_flavor_array_t           old_flavors);

PARAMETERS

thread
[in thread send right] The thread for which to set the ports.

exception_types
[in scalar] A flag word indicating the types of exceptions for which the exception port applies:

EXC_MASK_BAD_ACCESS
Could not access memory.

EXC_MASK_BAD_INSTRUCTION
Instruction failed. Illegal or undefined instruction or operand.

EXC_MASK_ARITHMETIC
Arithmetic exception

EXC_MASK_EMULATION
Emulation instruction. Emulation support instruction encountered.

EXC_MASK_SOFTWARE
Software generated exception.

EXC_MASK_BREAKPOINT
Trace, breakpoint, etc.

EXC_MASK_SYSCALL
System call requested.

EXC_MASK_MACH_SYSCALL
System call with a number in the Mach call range requested.

exception_port
[in exception send right] The exception port for all selected exception types.

behavior
[in scalar] Control of the behavior of the exception processing. Defined types are:

EXCEPTION_DEFAULT
Send a catch_exception_raise message including the thread identity.

EXCEPTION_DEFAULT_PROTECTED
Send a catch_exception_raise message including the thread identity. Mark the exception port (and associated exceptions) as protected.

EXCEPTION_STATE
Send a catch_exception_raise_state message including the thread state.

EXCEPTION_STATE_PROTECTED
Send a catch_exception_raise_state message including the thread state. Mark the exception port (and associated exceptions) as protected.

EXCEPTION_STATE_IDENTITY
Send a catch_exception_raise_state_identity message including the thread identity and state.

EXCEPTION_STATE_IDENTITY_PROTECTED
Send a catch_exception_raise_state_identity message including the thread identity and state. Mark the exception port (and associated exceptions) as protected.

flavor
[in scalar] The type of state to be sent with the exception message. These types are defined in \*L\*O.

old_exception_masks
[out array of exception_mask_t] An array, each element being a mask specifying for which exception types the corresponding element of the other arrays apply.

old_exception_count
[pointer to in/out scalar] On input, the maximum size of the array buffers; on output, the number of returned sets returned.

old_exception_ports
[out array of exception send rights] The returned exception ports.

old_behaviors
[out array of exception_behavior_t] The type of exception message to be sent as with behavior.

old_flavors
[out array of thread_state_flavor_t] The type of state to be sent with the exception message. These types are defined in \*L\*O.

DESCRIPTION

The thread_swap_exception_ports function sets a specified set of exception ports belonging to thread, returning the old set.

NOTES

If the value of the EXC_MACH_SYSCALL 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.

A "protected" exception port is one which cannot be fetched and for which exception processing cannot be aborted (thread_abort).

RETURN VALUES

KERN_EXCEPTION_PROTECTED
One of the requested exception ports is protected and cannot be returned.

RELATED INFORMATION

Functions: mach_thread_self, task_get_exception_ports, task_set_exception_ports, task_swap_exception_ports, thread_create, thread_get_exception_ports, thread_set_exception_ports, catch_exception_raise, thread_abort. \ No newline at end of file +

thread_swap_exception_ports

+
+

+Function - Swap exception ports for a thread. +

SYNOPSIS

+
+kern_return_t   thread_swap_exception_ports
+                (thread_act_t                            thread,
+                 exception_mask_t               exception_types,
+                 mach_port_t                     exception_port,
+                 exception_behavior_t                  behavior,
+                 thread_state_flavor_t                   flavor,
+                 exception_mask_array_t     old_exception_masks,
+                 old_exception_masks        old_exception_count,
+                 exception_port_array_t     old_exception_ports,
+                 exception_behavior_array_t       old_behaviors,
+                 exception_flavor_array_t           old_flavors);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +The thread for which to set the ports. +

+

exception_types +
+[in scalar] +A flag word indicating the types of exceptions for which the +exception port applies: +
+

+

EXC_MASK_BAD_ACCESS +
+Could not access memory. +

+

EXC_MASK_BAD_INSTRUCTION +
+Instruction failed. Illegal or undefined instruction or operand. +

+

EXC_MASK_ARITHMETIC +
+Arithmetic exception +

+

EXC_MASK_EMULATION +
+Emulation instruction. Emulation support instruction +encountered. +

+

EXC_MASK_SOFTWARE +
+Software generated exception. +

+

EXC_MASK_BREAKPOINT +
+Trace, breakpoint, etc. +

+

EXC_MASK_SYSCALL +
+System call requested. +

+

EXC_MASK_MACH_SYSCALL +
+System call with a number in the Mach call range requested. +
+

+

exception_port +
+[in exception send right] +The exception port for all selected exception +types. +

+

behavior +
+[in scalar] +Control of the behavior of the exception processing. Defined +types are: +
+

+

EXCEPTION_DEFAULT +
+Send a catch_exception_raise message including the thread +identity. +

+

EXCEPTION_DEFAULT_PROTECTED +
+Send a catch_exception_raise message including the thread +identity. Mark the exception port (and associated exceptions) +as protected. +

+

EXCEPTION_STATE +
+Send a catch_exception_raise_state message including the +thread state. +

+

EXCEPTION_STATE_PROTECTED +
+Send a catch_exception_raise_state message including the +thread state. Mark the exception port (and associated +exceptions) as protected. +

+

EXCEPTION_STATE_IDENTITY +
+Send a catch_exception_raise_state_identity message +including the thread identity and state. +

+

EXCEPTION_STATE_IDENTITY_PROTECTED +
+Send a catch_exception_raise_state_identity message +including the thread identity and state. Mark the exception port +(and associated exceptions) as protected. +
+

+

flavor +
+[in scalar] +The type of state to be sent with the exception message. +These types are defined in \*L\*O. +

+

old_exception_masks +
+[out array of exception_mask_t] +An array, each element being a mask +specifying for which exception types the corresponding element of the +other arrays apply. +

+

old_exception_count +
+[pointer to in/out scalar] +On input, the maximum size of the array +buffers; on output, the number of returned sets returned. +

+

old_exception_ports +
+[out array of exception send rights] +The returned exception ports. +

+

old_behaviors +
+[out array of exception_behavior_t] +The type of exception message to +be sent as with behavior. +

+

old_flavors +
+[out array of thread_state_flavor_t] +The type of state to be sent with +the exception message. These types are defined in +\*L\*O. +
+

DESCRIPTION

+

+The thread_swap_exception_ports function sets a specified +set of exception +ports belonging to thread, returning the old set. +

NOTES

+

+If the value of the EXC_MACH_SYSCALL 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. +

+A "protected" exception port is one which cannot be fetched and for which +exception processing cannot be aborted (thread_abort). +

RETURN VALUES

+
+

+

KERN_EXCEPTION_PROTECTED +
+One of the requested exception ports is protected and cannot be returned. +
+

RELATED INFORMATION

+

+Functions: +mach_thread_self, +task_get_exception_ports, +task_set_exception_ports, +task_swap_exception_ports, +thread_create, +thread_get_exception_ports, +thread_set_exception_ports, +catch_exception_raise, +thread_abort. 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 @@ -

vm_set_default_memory_manager

Function - Obsolete interface. Functionality now provided via host_set_default_memory_manager interface.

SYNOPSIS

kern_return_t   vm_set_default_memory_manager
                (host_priv_t                          host_priv,
                 mach_port_move_send_t          default_manager);

PARAMETERS

host_priv
[in host-control send right] The control port naming the host for which the default memory manager is to be set.

default_manager
[pointer to in/out default-pager send right] A memory manager port to the new default memory manager. If this value is MACH_PORT_NULL, the old memory manager is not changed. The old memory manager port is returned in this variable.

DESCRIPTION

The vm_set_default_memory_manager function establishes the default memory manager for a host. The named manager will be the target for future memory_object_create calls.

NOTES

The vm_set_default_memory_manager interface has been renamed to host_default_memory_manager. The old vm_set_default_memory_manager interface has been retained for backward compatibility, without the cluster_size parameter.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_create, vm_allocate. \ No newline at end of file +

vm_set_default_memory_manager

+
+

+Function - Obsolete interface. Functionality now provided via host_set_default_memory_manager interface.

SYNOPSIS

+
+kern_return_t   vm_set_default_memory_manager
+                (host_priv_t                          host_priv,
+                 mach_port_move_send_t          default_manager);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control send right] +The control port naming the host for which +the default memory manager is to be set. +

+

default_manager +
+[pointer to in/out default-pager send right] +A memory manager port to +the new default memory manager. If this value is MACH_PORT_NULL, +the old memory manager is not changed. The old memory +manager port is returned in this variable. +
+

DESCRIPTION

+

+The vm_set_default_memory_manager function establishes the default +memory manager for a host. The named manager will be the target for future +memory_object_create calls. +

NOTES

+The vm_set_default_memory_manager interface has been +renamed to host_default_memory_manager. The old +vm_set_default_memory_manager interface has been retained +for backward compatibility, without the cluster_size parameter. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_create, +vm_allocate. 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 @@ -

bootstrap_arguments

Function - Return a set of arguments to the bootstrap task.

SYNOPSIS

kern_return_t   bootstrap_arguments
                (mach_port_t                          bootstrap,
                 task_t                                    task,
                 pointer_t                            pointer_t,
                 mach_msg_type_number_t  mach_msg_type_number_t);

PARAMETERS

bootstrap
[in bootstrap send right] The bootstrap port for the task, obtained from task_get_special_ports.

task
[in task send right] The task port for the task whose argument strings are requested.

arguments
[pointer to dynamic out array of characters] The argument strings for the task. This is an array of argumentCnt bytes, containing NUL characters separating the strings.

argumentsCnt
[out pointer to scalar] Number of bytes contained in arguments.

DESCRIPTION

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 libsa_mach.a standalone Mach C runtime startup code uses bootstrap_arguments and bootstrap_environment to initialize argc, argv, and envp for main.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: bootstrap_ports, bootstrap_environment. \ No newline at end of file +

bootstrap_arguments

+
+

+Function - Return a set of arguments to the bootstrap task. +

SYNOPSIS

+
+kern_return_t   bootstrap_arguments
+                (mach_port_t                          bootstrap,
+                 task_t                                    task,
+                 pointer_t                            pointer_t,
+                 mach_msg_type_number_t  mach_msg_type_number_t);
+
+

PARAMETERS

+
+

+

bootstrap +
+[in bootstrap send right] +The bootstrap port for the task, obtained from +task_get_special_ports. +

+

task +
+[in task send right] +The task port for the task whose argument strings are requested. +

+

arguments +
+[pointer to dynamic out array of characters] +The argument strings for the task. This is an array of +argumentCnt bytes, containing NUL characters +separating the strings. +

+

argumentsCnt +
+[out pointer to scalar] +Number of bytes contained in arguments. +
+

DESCRIPTION

+

+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 libsa_mach.a +standalone Mach C runtime startup code uses bootstrap_arguments and +bootstrap_environment to initialize argc, argv, +and envp for main. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +bootstrap_ports, +bootstrap_environment. + 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 @@ -

bootstrap_completed

Server Interface - Inform bootstrap server that initialization is complete.

SYNOPSIS

kern_return_t   bootstrap_completed
                (mach_port_t                     bootstrap_port,
                 task_t                                    task);

PARAMETERS

bootstrap_port
The port representing the calling task's bootstrap server.

task
This parameter represents the calling task.

DESCRIPTION

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.

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 bootstrap.conf file) and the server just invoked never sends this message, the bootstrap server will wait forever.

NOTES

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.)

RETURN VALUES

KERN_SUCCESS
The bootstrap server has updated the calling server's state with respect to bootstrap completion.

KERN_INVALID_ARGUMENT
The bootstrap server does not recognize the calling server (the task specified by the task parameter).

RELATED INFORMATION

Functions: \ No newline at end of file +

bootstrap_completed

+
+

+Server Interface - Inform bootstrap server that +initialization is complete. +

SYNOPSIS

+
+kern_return_t   bootstrap_completed
+                (mach_port_t                     bootstrap_port,
+                 task_t                                    task);
+
+

PARAMETERS

+
+

+

bootstrap_port +
+The port representing the calling task's bootstrap server. +

+

task +
+This parameter represents the calling task. +
+

DESCRIPTION

+

+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. +

+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 bootstrap.conf file) and the server just invoked never +sends this message, the bootstrap server will wait forever. +

NOTES

+

+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.) +

RETURN VALUES

+
+

+

KERN_SUCCESS +
+The bootstrap server has updated the calling server's state with +respect to bootstrap completion. +

+

KERN_INVALID_ARGUMENT +
+The bootstrap server does not recognize the calling server (the task +specified by the task parameter). +
+

RELATED INFORMATION

+

+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 @@ -

bootstrap_environment

Function - Return to the bootstrap task an array of strings specifying the task's environment.

SYNOPSIS

kern_return_t   bootstrap_environment
                (mach_port_t                          bootstrap,
                 task_t                                    task,
                 pointer_t                            pointer_t,
                 mach_msg_type_number_t  mach_msg_type_number_t);

PARAMETERS

bootstrap
[in bootstrap send right] The bootstrap port for the task, obtained from task_get_special_ports.

task
[in task send right] The task port for the task whose argument strings are requested.

environment
[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.

environmentCnt
[out pointer to scalar] Number of bytes contained in _environment_.

DESCRIPTION

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 bootstrap_arguments and bootstrap_environment to initialize argc, argv, and envp for main.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: bootstrap_ports, bootstrap_arguments. \ No newline at end of file +

bootstrap_environment

+
+

+Function - Return to the bootstrap task an array of strings specifying the task's environment. +

SYNOPSIS

+
+kern_return_t   bootstrap_environment
+                (mach_port_t                          bootstrap,
+                 task_t                                    task,
+                 pointer_t                            pointer_t,
+                 mach_msg_type_number_t  mach_msg_type_number_t);
+
+

PARAMETERS

+
+

+

bootstrap +
+[in bootstrap send right] +The bootstrap port for the task, obtained from +task_get_special_ports. +

+

task +
+[in task send right] +The task port for the task whose argument strings are requested. +

+

environment +
+[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. +

+

environmentCnt +
+[out pointer to scalar] +Number of bytes contained in _environment_. +
+

DESCRIPTION

+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 bootstrap_arguments and +bootstrap_environment to initialize argc, argv, +and envp for main. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +bootstrap_ports, +bootstrap_arguments. + + 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 @@ -

bootstrap_ports

Function - Return send rights to the system's control ports.

SYNOPSIS

kern_return_t   bootstrap_ports
                (mach_port_t                          bootstrap,
                 bootstrap                         host_control,
                 host_control                     device_master,
                 device_master                root_wired_ledger,
                 root_wired_ledger            root_paged_ledger,
                 bootstrap                             security);

PARAMETERS

bootstrap
[in bootstrap send right] The bootstrap port obtained from \*Ltask_get_special_ports()\*O.

host_priv
[out host-control send right] The control port for the host.

device_master
[out device-master send right] The device master port.

root_wired_ledger
[out ledger send right] The root wired kernel memory ledger port.

root_paged_ledger
[out ledger send right] The root default memory managed space ledger port.

security
[out security send right] The host security port, used for setting task identity.

DESCRIPTION

The bootstrap_ports 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 TASK_BOOTSTRAP_PORT 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.

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: device_open, host_get_clock_control, host_get_clock_service, host_processor_set_priv, host_processors, ledger_create, task_set_security_token. \ No newline at end of file +

bootstrap_ports

+
+

+Function - Return send rights to the system's control ports. +

SYNOPSIS

+
+kern_return_t   bootstrap_ports
+                (mach_port_t                          bootstrap,
+                 bootstrap                         host_control,
+                 host_control                     device_master,
+                 device_master                root_wired_ledger,
+                 root_wired_ledger            root_paged_ledger,
+                 bootstrap                             security);
+
+

PARAMETERS

+
+

+

bootstrap +
+[in bootstrap send right] +The bootstrap port obtained from \*Ltask_get_special_ports()\*O. +

+

host_priv +
+[out host-control send right] +The control port for the host. +

+

device_master +
+[out device-master send right] +The device master port. +

+

root_wired_ledger +
+[out ledger send right] +The root wired kernel memory ledger port. +

+

root_paged_ledger +
+[out ledger send right] +The root default memory managed space ledger +port. +

+

security +
+[out security send right] +The host security port, used for setting task +identity. +
+

DESCRIPTION

+

+The bootstrap_ports 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 TASK_BOOTSTRAP_PORT 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. +

+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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +device_open, +host_get_clock_control, +host_get_clock_service, +host_processor_set_priv, +host_processors, +ledger_create, +task_set_security_token. 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 @@ -

catch_exception_raise

Server Interface - Handles the occurrence of an exception within a thread.

SYNOPSIS

kern_return_t   catch_exception_raise
                (mach_port_t                          exception_port,
                 mach_port_t                                  thread,
                 mach_port_t                                    task,
                 exception_type_t                          exception,
                 exception_data_t                               code,
                 mach_msg_type_number_t                   code_count);

catch_exception_raise_state expanded form: 

kern_return_t   catch_exception_raise_state
                (mach_port_t                          exception_port,
                 exception_type_t                          exception,
                 exception_data_t                               code,
                 mach_msg_type_number_t                   code_count,
                 int *                                        flavor,
                 thread_state_t                             in_state,
                 mach_msg_type_number_t               in_state_count,
                 thread_state_t                            out_state,
                 mach_msg_type_number_t *            out_state_count);

catch_exception_raise_state_identity expanded form: 

kern_return_t   catch_exception_raise_state_identity
                (mach_port_t                          exception_port,
                 mach_port_t                                  thread,
                 mach_port_t                                    task,
                 exception_type_t                          exception,
                 exception_data_t                               code,
                 mach_msg_type_number_t                   code_count,
                 int *                                        flavor,
                 thread_state_t                             in_state,
                 mach_msg_type_number_t               in_state_count,
                 thread_state_t                            out_state,
                 mach_msg_type_number_t *            out_state_count);

PARAMETERS

exception_port
[in exception (receive) right] The port to which the exception notification was sent.

thread
[in thread-self send right] The thread self port for the thread taking the exception.

task
[in task-self send right] The task self port for the task containing the thread taking the exception.

exception
[in scalar] The type of the exception. The machine independent values raised by all implementations are:

EXC_BAD_ACCESS
Could not access memory. subcode contains the bad memory address.

EXC_BAD_INSTRUCTION
Instruction failed. Illegal or undefined instruction or operand.

EXC_ARITHMETIC
Arithmetic exception; exact nature of exception is in subcode field.

EXC_EMULATION
Emulation instruction. Emulation support instruction encountered. Details in subcode field.

EXC_SOFTWARE
Software generated exception; exact exception is in subcode field. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000 - 0x1FFFF reserved for OS emulation.

EXC_BREAKPOINT
Trace, breakpoint, etc. Details in subcode field.

EXC_SYSCALL
System call requested. Details in subcode field.

EXC_MACH_SYSCALL
System call with a number in the Mach call range requested. Details in subcode field.
code
[in scalar] A machine dependent array indicating a particular instance of exception.

code_count
[in scalar] The size of the buffer (in natural-sized units).

flavor
[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.

in_state
[pointer to in structure] State information of the thread at the time of the exception.

in_state_count
[in scalar] The size of the in state buffer (in natural-sized units).

out_state
[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.

out_state_count
[pointer to out scalar] The size of the out state buffer (in natural-sized units).

DESCRIPTION

A catch_exception_raise function is called by exc_server as the result of a kernel message indicating that an exception occurred within a thread. The exception_port parameter specifies the port named via a previous call to thread_set_exception_ports or task_set_exception_ports as the port that responds when the thread takes an exception.

The alternate message forms (the format being selected when the exception port was set) allow for selected thread state to be included.

NOTES

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 mach_msg_server) to this port, using the exc_server function to decode the messages and then call the linked in catch_exception_raise. It is the job of catch_exception_raise to handle the exception and decide the course of action for thread.

If the thread should continue from the point of exception, catch_exception_raise 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 catch_exception_raise:

thread_suspend
This keeps the thread from proceeding after the next step.

thread_abort
This aborts the message receive operation currently blocking the thread.

thread_set_state
(if using the catch_exception_raise form). Set the thread's state so that it continues doing something else.

thread_resume
Let the thread start running from its new state.
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 thread_abort destroys, so replying to the message is harmless.) The thread can always be destroyed with thread_terminate.

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.

To get the effect of a non-success return value, the server interface should return MIG_DESTROY_REQUEST. This causes exc_server and mach_msg_server to destroy the kernel's request (as opposed to sending a reply with a KERN_SUCCESS value).

RETURN VALUES

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 mach_msg_server to remove the task and thread port references.

RELATED INFORMATION

Functions: exc_server, thread_abort, task_get_exception_ports, thread_get_exception_ports, thread_get_state, thread_resume, task_set_exception_ports, thread_set_exception_ports, task_swap_exception_ports, thread_swap_exception_ports, thread_set_state, thread_suspend, thread_terminate. \ No newline at end of file +

catch_exception_raise

+
+

+Server Interface - Handles the occurrence of an exception within a thread. + +

SYNOPSIS

+
+kern_return_t   catch_exception_raise
+                (mach_port_t                          exception_port,
+                 mach_port_t                                  thread,
+                 mach_port_t                                    task,
+                 exception_type_t                          exception,
+                 exception_data_t                               code,
+                 mach_msg_type_number_t                   code_count);
+
+

+catch_exception_raise_state +expanded form: +

+kern_return_t   catch_exception_raise_state
+                (mach_port_t                          exception_port,
+                 exception_type_t                          exception,
+                 exception_data_t                               code,
+                 mach_msg_type_number_t                   code_count,
+                 int *                                        flavor,
+                 thread_state_t                             in_state,
+                 mach_msg_type_number_t               in_state_count,
+                 thread_state_t                            out_state,
+                 mach_msg_type_number_t *            out_state_count);
+
+

+catch_exception_raise_state_identity +expanded form: +

+kern_return_t   catch_exception_raise_state_identity
+                (mach_port_t                          exception_port,
+                 mach_port_t                                  thread,
+                 mach_port_t                                    task,
+                 exception_type_t                          exception,
+                 exception_data_t                               code,
+                 mach_msg_type_number_t                   code_count,
+                 int *                                        flavor,
+                 thread_state_t                             in_state,
+                 mach_msg_type_number_t               in_state_count,
+                 thread_state_t                            out_state,
+                 mach_msg_type_number_t *            out_state_count);
+
+

PARAMETERS

+
+
exception_port +
+[in exception (receive) right] The port to which the exception +notification was sent. +

+

thread +
+[in thread-self send right] The thread self port for the thread taking the +exception. +

+

task +
+[in task-self send right] The task self port for the task containing the +thread taking the exception. +

+

exception +
+[in scalar] The type of the exception. +The machine independent values raised by all implementations are: +
+

+

EXC_BAD_ACCESS +
+Could not access memory. subcode contains the bad memory +address. +

+

EXC_BAD_INSTRUCTION +
+Instruction failed. Illegal or undefined instruction or operand. +

+

EXC_ARITHMETIC +
+Arithmetic exception; exact nature of exception is in subcode +field. +

+

EXC_EMULATION +
+Emulation instruction. Emulation support instruction encountered. +Details in subcode field. +

+

EXC_SOFTWARE +
+Software generated exception; exact exception is in subcode +field. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000 +- 0x1FFFF reserved for OS emulation. +

+

EXC_BREAKPOINT +
+Trace, breakpoint, etc. Details in subcode field. +

+

EXC_SYSCALL +
+System call requested. Details in subcode field. +

+

EXC_MACH_SYSCALL +
+System call with a number in the Mach call range requested. +Details in subcode field. +
+
code +
+[in scalar] A machine dependent array indicating a particular instance +of exception. +

+

code_count +
+[in scalar] The size of the buffer (in natural-sized units). +

+

flavor +
+[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. +

+

in_state +
+[pointer to in structure] State information of the thread at the time of +the exception. +

+

in_state_count +
+[in scalar] The size of the in state buffer (in natural-sized units). +

+

out_state +
+[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. +

+

out_state_count +
+[pointer to out scalar] The size of the out state buffer (in natural-sized units). +
+

DESCRIPTION

+

+A catch_exception_raise function is called by +exc_server as the result of a +kernel message indicating that an exception occurred within a thread. +The exception_port parameter specifies the port named via +a previous call to thread_set_exception_ports or +task_set_exception_ports +as the port that responds when the thread takes an +exception. +

+The alternate message forms (the format being selected when the exception port +was set) allow for selected thread state to be included. + +

NOTES

+

+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 mach_msg_server) to this +port, using the exc_server function +to decode the messages and then call the +linked in catch_exception_raise. +It is the job of catch_exception_raise to handle +the exception and decide the course of action for thread. +

+If the thread should continue from the point of exception, +catch_exception_raise 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 catch_exception_raise: +

+
thread_suspend +
+ This keeps the thread from proceeding after the next step. +

+

thread_abort +
+ This aborts the message receive operation currently blocking +the thread. +

+

thread_set_state +
+ (if using the catch_exception_raise form). Set the +thread's state so that it continues doing something else. +

+

thread_resume +
+ Let the thread start running from its new state. +
+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 thread_abort destroys, so replying to the message is harmless.) +The thread can always be destroyed with thread_terminate. +

+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. +

+To get the effect of a non-success return value, the server interface should return +MIG_DESTROY_REQUEST. This causes exc_server and mach_msg_server +to destroy the kernel's request (as opposed to sending a reply with a +KERN_SUCCESS value). + +

RETURN VALUES

+

+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 +mach_msg_server to remove the task and thread port references. + +

RELATED INFORMATION

+

+Functions: +exc_server, +thread_abort, +task_get_exception_ports, +thread_get_exception_ports, +thread_get_state, +thread_resume, +task_set_exception_ports, +thread_set_exception_ports, +task_swap_exception_ports, +thread_swap_exception_ports, +thread_set_state, +thread_suspend, +thread_terminate. 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 @@ -

clock_alarm

Function - Set off an alarm.

SYNOPSIS

kern_return_t   clock_alarm
                (clock_t                             clock_name,
                 alarm_type_t                        alarm_type,
                 tvalspec_t                          alarm_time,
                 mach_port_t                   alarm_reply_port);

PARAMETERS

clock_name
[in clock-name send right] The name (or control) port for the clock.

alarm_type
[in scalar] How to interpret the alarm_time value:

TIME_RELATIVE
Interpret the alarm time as relative to the current time.

TIME_ABSOLUTE
Interpret the alarm time as an absolute time.

alarm_time
[in structure] The time when the alarm is to be sent.

alarm_reply_port
[in alarm receive (to be converted to send-once) right] A port into which the alarm message is to be sent.

DESCRIPTION

The clock_alarm 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 clock_alarm_reply server interface.

NOTES

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.

The alarm will be serviced at the service time nearest the specified alarm time as governed by the current clock alarm resolution.

Not all clocks implement this service, but the REALTIME clock must. If the clock does not provide this service, this call is ignored.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_get_clock_service, clock_get_attributes, clock_get_time, clock_sleep, clock_alarm_reply.

Data Structures: tvalspec. \ No newline at end of file +

clock_alarm

+
+

+Function - Set off an alarm. +

SYNOPSIS

+
+kern_return_t   clock_alarm
+                (clock_t                             clock_name,
+                 alarm_type_t                        alarm_type,
+                 tvalspec_t                          alarm_time,
+                 mach_port_t                   alarm_reply_port);
+
+

PARAMETERS

+
+

+

clock_name +
+[in clock-name send right] +The name (or control) port for the clock. +

+

alarm_type +
+[in scalar] +How to interpret the alarm_time value: +
+

+

TIME_RELATIVE +
+Interpret the alarm time as relative to the current time. +

+

TIME_ABSOLUTE +
+Interpret the alarm time as an absolute time. +
+

+

alarm_time +
+[in structure] +The time when the alarm is to be sent. +

+

alarm_reply_port +
+[in alarm receive (to be converted to send-once) right] +A port into +which the alarm message is to be sent. +
+

DESCRIPTION

+

+The clock_alarm 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 +clock_alarm_reply server interface. +

NOTES

+

+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. +

+The alarm will be serviced at the service time nearest the specified +alarm time +as governed by the current clock alarm resolution. +

+Not all clocks implement this service, but the REALTIME clock must. If the +clock does not provide this service, this call is ignored. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_get_clock_service, +clock_get_attributes, +clock_get_time, +clock_sleep, +clock_alarm_reply. +

+Data Structures: +tvalspec. 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 @@ -

clock_alarm_reply

Function - Ring a preset alarm.

SYNOPSIS

kern_return_t   clock_alarm_reply
                (reply_port_t                  alarm_reply_port,
                 kern_return_t                       reply_code,
                 alarm_type_t                        alarm_type,
                 tvalspec_t                           wake_time);

PARAMETERS

alarm_reply_port
[in alarm (receive) right] The reply port named in the corresponding clock_alarm call.

reply_code
[in scalar] The reply status code from the alarm. The possible values are:

KERN_SUCCESS
The alarm was delivered without problem.

KERN_INVALID_VALUE
The alarm_type and/or alarm_time values supplied to clock_alarm were invalid.

KERN_INVALID_LEDGER
The ledger supplied to clock_alarm was not a ledger.

KERN_ABORTED
The alarm was terminated via use of clock_set_time.

alarm_type
[in scalar] The alarm type value supplied to the clock_alarm 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.

wake_time
[in structure] The time when the alarm message was sent.

DESCRIPTION

A clock_alarm_reply function is called as the result of a message from the kernel indicating that a previously requested alarm time (clock_alarm) has arrived.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_get_clock_service, clock_get_attributes, clock_get_time, clock_sleep, clock_alarm, clock_reply_server, clock_set_time.

Data Structures: tvalspec. \ No newline at end of file +

clock_alarm_reply

+
+

+Function - Ring a preset alarm. +

SYNOPSIS

+
+kern_return_t   clock_alarm_reply
+                (reply_port_t                  alarm_reply_port,
+                 kern_return_t                       reply_code,
+                 alarm_type_t                        alarm_type,
+                 tvalspec_t                           wake_time);
+
+

PARAMETERS

+
+

+

alarm_reply_port +
+[in alarm (receive) right] +The reply port named in the corresponding +clock_alarm call. +

+

reply_code +
+[in scalar] +The reply status code from the alarm. The possible values +are: +
+

+

KERN_SUCCESS +
+The alarm was delivered without problem. +

+

KERN_INVALID_VALUE +
+The alarm_type and/or alarm_time values supplied to +clock_alarm were invalid. +

+

KERN_INVALID_LEDGER +
+The ledger supplied to clock_alarm was not a ledger. +

+

KERN_ABORTED +
+The alarm was terminated via use of clock_set_time. +
+

+

alarm_type +
+[in scalar] +The alarm type value supplied to the clock_alarm 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. +

+

wake_time +
+[in structure] +The time when the alarm message was sent. +
+

DESCRIPTION

+

+A clock_alarm_reply function is called as the result +of a message from the +kernel indicating that a previously requested alarm time (clock_alarm) +has arrived. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_get_clock_service, +clock_get_attributes, +clock_get_time, +clock_sleep, +clock_alarm, +clock_reply_server, +clock_set_time. +

+Data Structures: +tvalspec. 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 @@ -

clock_get_attributes

Function - Return attributes of a clock.

SYNOPSIS

kern_return_t   clock_get_attributes
                (clock_t                             clock_name,
                 clock_flavor_t                          flavor,
                 clock_attr_t                         attribute,
                 mach_msg_type_number_t         attribute_count);

PARAMETERS

clock_name
[in clock-name send right] The name (or control) port for the clock.

flavor
[in scalar] Type of information desired. Defined values are:

CLOCK_GET_TIME_RES
The resolution, in nanoseconds, with which the value returned by clock_get_time is updated.

CLOCK_MAP_TIME_RES
The resolution, in nanoseconds, with which the value visible via clock_map_time is updated.

CLOCK_ALARM_CURRES
The resolution, in nanoseconds, at which clock alarm and sleep timers are currently serviced.

CLOCK_ALARM_MINRES
The minimum resolution, in nanoseconds, at which clock alarm and sleep timers can be serviced.

CLOCK_ALARM_MAXRES
The maximum resolution, in nanoseconds, at which clock alarm and sleep timers can be serviced.

attribute
[out scalar] The returned attribute.

attribute_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The clock_get_attributes function returns attributes of a clock's implementation or operation.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_get_clock_service, clock_get_time, clock_map_time, clock_sleep, clock_alarm, clock_set_attributes. \ No newline at end of file +

clock_get_attributes

+
+

+Function - Return attributes of a clock. +

SYNOPSIS

+
+kern_return_t   clock_get_attributes
+                (clock_t                             clock_name,
+                 clock_flavor_t                          flavor,
+                 clock_attr_t                         attribute,
+                 mach_msg_type_number_t         attribute_count);
+
+

PARAMETERS

+
+

+

clock_name +
+[in clock-name send right] +The name (or control) port for the clock. +

+

flavor +
+[in scalar] +Type of information desired. Defined values are: +
+

+

CLOCK_GET_TIME_RES +
+The resolution, in nanoseconds, with which the value returned +by clock_get_time is updated. +

+

CLOCK_MAP_TIME_RES +
+The resolution, in nanoseconds, with which the value visible +via clock_map_time is updated. +

+

CLOCK_ALARM_CURRES +
+The resolution, in nanoseconds, at which clock alarm and +sleep timers are currently serviced. +

+

CLOCK_ALARM_MINRES +
+The minimum resolution, in nanoseconds, at which clock +alarm and sleep timers can be serviced. +

+

CLOCK_ALARM_MAXRES +
+The maximum resolution, in nanoseconds, at which clock +alarm and sleep timers can be serviced. +
+

+

attribute +
+[out scalar] +The returned attribute. +

+

attribute_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The clock_get_attributes function returns attributes of a clock's +implementation or operation. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_get_clock_service, +clock_get_time, +clock_map_time, +clock_sleep, +clock_alarm, +clock_set_attributes. 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 @@ -

clock_get_time

Function - Return the current time.

SYNOPSIS

kern_return_t   clock_get_time
                (clock_t                             clock_name,
                 tvalspec_t                            cur_time);

PARAMETERS

clock_name
[in clock-name send right] The name (or control) port for the clock.

cur_time
[out structure] Current time

DESCRIPTION

The clock_get_time function returns the current time kept by a clock. The value returned is a monotonically increasing value (unless tampered with via the clock_set_time function).

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_get_clock_service, clock_get_attributes, clock_map_time, clock_sleep, clock_alarm, clock_set_time.

Data Structures: tvalspec. \ No newline at end of file +

clock_get_time

+
+

+Function - Return the current time. +

SYNOPSIS

+
+kern_return_t   clock_get_time
+                (clock_t                             clock_name,
+                 tvalspec_t                            cur_time);
+
+

PARAMETERS

+
+

+

clock_name +
+[in clock-name send right] +The name (or control) port for the clock. +

+

cur_time +
+[out structure] +Current time +
+

DESCRIPTION

+

+The clock_get_time function returns the current time +kept by a clock. The +value returned is a monotonically increasing value (unless tampered +with via the +clock_set_time function). +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_get_clock_service, +clock_get_attributes, +clock_map_time, +clock_sleep, +clock_alarm, +clock_set_time. +

+Data Structures: +tvalspec. 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 @@ -

clock_map_time

Function - Return a memory object that maps a clock.

SYNOPSIS

kern_return_t   clock_map_time
                (clock_t                             clock_name,
                 memory_object_t                   clock_memory);

PARAMETERS

clock_name
[in clock-name send right] The name (or control) port for the clock.

clock_memory
[out memory-object-representative send right] Mapped clock time memory object representative.

DESCRIPTION

The clock_map_time 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 mapped_tvalspec). The returned right is suitable as an argument for vm_map.

NOTES

Not all clocks provide this service, but the REALTIME clock must.

RETURN VALUES

KERN_FAILURE
The specified clock does not provide this service.

RELATED INFORMATION

Functions: host_get_clock_service, clock_get_attributes, clock_get_time, clock_sleep, clock_alarm.

Data Structures: mapped_tvalspec. \ No newline at end of file +

clock_map_time

+
+

+Function - Return a memory object that maps a clock. +

SYNOPSIS

+
+kern_return_t   clock_map_time
+                (clock_t                             clock_name,
+                 memory_object_t                   clock_memory);
+
+

PARAMETERS

+
+

+

clock_name +
+[in clock-name send right] +The name (or control) port for the clock. +

+

clock_memory +
+[out memory-object-representative send right] +Mapped clock time +memory object representative. +
+

DESCRIPTION

+

+The clock_map_time 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 mapped_tvalspec). +The returned right is suitable as an argument for vm_map. +

NOTES

+

+Not all clocks provide this service, but the REALTIME clock must. +

RETURN VALUES

+
+

+

KERN_FAILURE +
+The specified clock does not provide this service. +
+

RELATED INFORMATION

+

+Functions: +host_get_clock_service, +clock_get_attributes, +clock_get_time, +clock_sleep, +clock_alarm. +

+Data Structures: +mapped_tvalspec. 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 @@ -

clock_reply_server

Function - Handle kernel-generated alarm.

SYNOPSIS

boolean_t	clock_reply_server
		(mach_msg_header_t	request_msg,
		mach_msg_header_t	reply_ms);

PARAMETERS

in_msg
[pointer to in structure] The alarm message received from the kernel.

out_msg
[out structure] Not used.

DESCRIPTION

The clock_reply_server 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 clock_alarm call. The clock_reply_server function performs all necessary argument handling for this kernel message and calls the appropriate handling function. These functions must be supplied by the caller.

RETURN VALUES

TRUE
The message was handled and the appropriate function was called.

FALSE
The message did not apply to the alarm mechanism and no other action was taken.

RELATED INFORMATION

Functions: clock_alarm_reply. \ No newline at end of file +

clock_reply_server

+
+

+Function - Handle kernel-generated alarm. +

SYNOPSIS

+
+boolean_t	clock_reply_server
+		(mach_msg_header_t	request_msg,
+		mach_msg_header_t	reply_ms);
+
+

PARAMETERS

+
+

+

in_msg +
+[pointer to in structure] +The alarm message received from the kernel. +

+

out_msg +
+[out structure] +Not used. +
+

DESCRIPTION

+

+The clock_reply_server 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 clock_alarm +call. The clock_reply_server function performs all necessary +argument handling for +this kernel message and calls the appropriate handling function. These functions +must be supplied by the caller. +

RETURN VALUES

+
+

+

TRUE +
+The message was handled and the appropriate function was called. +

+

FALSE +
+The message did not apply to the alarm mechanism and no other action +was taken. +
+

RELATED INFORMATION

+

+Functions: +clock_alarm_reply. 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 @@ -

clock_set_attributes

Function - Set a particular clock's attributes.

SYNOPSIS

kern_return_t   clock_set_attributes
                (clock_ctrl_t                     clock_control,
                 clock_flavor_t                          flavor,
                 clock_attr_t                         attribute,
                 clock_control                  attribute_count);

PARAMETERS

clock_control
[in clock-control send right] The control port for the clock.

flavor
[in scalar] Type of information to be set. Defined values are:

CLOCK_ALARM_CURRES
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.

attribute
[pointer to in scalar] New attribute.

attribute_count
[in scalar] The size of the buffer (in natural-sized units).

DESCRIPTION

The clock_set_attributes function sets attributes of a clock's operation.

NOTES

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_get_clock_control, clock_set_time, clock_get_attributes. \ No newline at end of file +

clock_set_attributes

+
+

+Function - Set a particular clock's attributes. +

SYNOPSIS

+
+kern_return_t   clock_set_attributes
+                (clock_ctrl_t                     clock_control,
+                 clock_flavor_t                          flavor,
+                 clock_attr_t                         attribute,
+                 clock_control                  attribute_count);
+
+

PARAMETERS

+
+

+

clock_control +
+[in clock-control send right] +The control port for the clock. +

+

flavor +
+[in scalar] +Type of information to be set. Defined values are: +
+

+

CLOCK_ALARM_CURRES +
+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. +
+

+

attribute +
+[pointer to in scalar] +New attribute. +

+

attribute_count +
+[in scalar] +The size of the buffer (in natural-sized units). +
+

DESCRIPTION

+

+The clock_set_attributes function sets attributes of +a clock's operation. +

NOTES

+

+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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_get_clock_control, +clock_set_time, +clock_get_attributes. 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 @@ -

clock_set_time

Function - Set the current time.

SYNOPSIS

kern_return_t   clock_set_time
                (clock_ctrl_t                     clock_control,
                 tvalspec_t                            new_time);

PARAMETERS

clock_control
[in clock-control send right] The control port for the clock.

new_time
[in structure] New time

DESCRIPTION

The clock_set_time 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 KERN_ABORTED.

CAUTIONS

The use of this function is \*Vstrongly discouraged\*O since it could affect the monotonically increasing nature of the clock.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_get_clock_control, clock_set_attributes, clock_get_time, clock_alarm, clock_sleep.

Data Structures: tvalspec. \ No newline at end of file +

clock_set_time

+
+

Function - Set the current time. +

SYNOPSIS

+
+kern_return_t   clock_set_time
+                (clock_ctrl_t                     clock_control,
+                 tvalspec_t                            new_time);
+
+

PARAMETERS

+
+

+

clock_control +
+[in clock-control send right] +The control port for the clock. +

+

new_time +
+[in structure] +New time +
+

DESCRIPTION

+

+The clock_set_time 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 KERN_ABORTED. +

CAUTIONS

+

+The use of this function is \*Vstrongly discouraged\*O since it could affect the +monotonically increasing nature of the clock. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_get_clock_control, +clock_set_attributes, +clock_get_time, +clock_alarm, +clock_sleep. +

+Data Structures: +tvalspec. 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 @@ -

clock_sleep

System Trap - Sleep until a given time.

SYNOPSIS

kern_return_t   clock_sleep
                (mach_port_t                         clock_name,
                 sleep_type_t                        sleep_type,
                 tvalspec_t                          sleep_time,
                 clock_name                           wake_time);

PARAMETERS

clock_name
[in clock-name send right] The name (or control) port for the clock.

sleep_type
[in scalar] How to interpret the sleep_time value:

TIME_RELATIVE
Interpret the sleep time as relative to the current time.

TIME_ABSOLUTE
Interpret the sleep time as an absolute time.

sleep_time
[in structure] The time when the sleep is to terminate.

wake_time
[out structure] The actual (absolute) time at which the sleep terminated.

DESCRIPTION

The clock_sleep system trap delays the invoking thread until a specified time. This sleep may be aborted by thread_abort. Not all clocks provide this service but the REALTIME clock must.

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 (clock_set_time), 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.

RETURN VALUES

KERN_FAILURE
The clock does not support a sleep service.

KERN_ABORTED
The sleep was interrupted by thread_abort or terminated via use of clock_set_time.

RELATED INFORMATION

Functions: host_get_clock_service, clock_get_attributes, clock_get_time, clock_alarm, clock_set_time, thread_abort,

Data Structures: tvalspec. \ No newline at end of file +

clock_sleep

+
+

+System Trap - Sleep until a given time. +

SYNOPSIS

+
+kern_return_t   clock_sleep
+                (mach_port_t                         clock_name,
+                 sleep_type_t                        sleep_type,
+                 tvalspec_t                          sleep_time,
+                 clock_name                           wake_time);
+
+

PARAMETERS

+
+

+

clock_name +
+[in clock-name send right] The name (or control) port for the clock. +

+

sleep_type +
+[in scalar] How to interpret the sleep_time value: +
+

+

TIME_RELATIVE +
+Interpret the sleep time as relative to the current time. +

+

TIME_ABSOLUTE +
+Interpret the sleep time as an absolute time. +
+

+

sleep_time +
+[in structure] The time when the sleep is to terminate. +

+

wake_time +
+[out structure] The actual (absolute) time at which the sleep terminated. +
+ +

DESCRIPTION

+

+The clock_sleep system trap delays the invoking +thread until a specified time. This sleep may be aborted by +thread_abort. Not all clocks provide this service +but the REALTIME clock must. +

+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 (clock_set_time), 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. +

RETURN VALUES

+
+

+

KERN_FAILURE +
+The clock does not support a sleep service. +

+

KERN_ABORTED +
+The sleep was interrupted by thread_abort or terminated via use of +clock_set_time. +
+

RELATED INFORMATION

+

+Functions: +host_get_clock_service, +clock_get_attributes, +clock_get_time, +clock_alarm, +clock_set_time, +thread_abort, +

+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 @@ -

default_pager_add_segment

Server Interface - Add additional backing storage for a default pager.

SYNOPSIS

#include< mach/default_pager_object.h>

kern_return_t   default_pager_add_segment
                (mach_port_t                      backing_store,
                 mach_port_t                             device,
                 recnum_t                                offset,
                 recnum_t                                 count,
                 int                                record_size);

PARAMETERS

backing_store
[in backing store (receive) right] The backing store port.

device
[in device port] The port for the device containing the backing storage partition.

offset
[in scalar] The offset, in record_size units, to the beginning of the backing storage on the device.

count
[in scalar] The number of record_size units in the partition/segment.

record_size
[in scalar] The size, in bytes, of the storage device record.

DESCRIPTION

The default_pager_add_segment 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 default_pager_backing_store_create, 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).

RETURN VALUES

KERN_FAILURE
The default pager does not support this operation.

KERN_INVALID_ARGUMENT
The backing_store port does not represent a valid backing store or the specified segment overlaps an existing partition.

KERN_RESOURCE_SHORTAGE
The default pager is unable to allocate internal resources to manage the new backing storage.

KERN_SUCCESS
The operation was successful.

RELATED INFORMATION

Functions: default_pager_backing_store_create, default_pager_backing_store_delete, default_pager_backing_store_info. \ No newline at end of file +

default_pager_add_segment

+
+

+Server Interface - Add additional backing storage for a default pager. +

SYNOPSIS

+
+#include< mach/default_pager_object.h>
+
+kern_return_t   default_pager_add_segment
+                (mach_port_t                      backing_store,
+                 mach_port_t                             device,
+                 recnum_t                                offset,
+                 recnum_t                                 count,
+                 int                                record_size);
+
+

PARAMETERS

+
+

+

backing_store +
+[in backing store (receive) right] The backing store port. +

+

device +
+[in device port] The port for the device containing the backing storage +partition. +

+

offset +
+[in scalar] The offset, in record_size units, to the beginning of the +backing storage on the device. +

+

count +
+[in scalar] The number of record_size units +in the partition/segment. +

+

record_size +
+[in scalar] The size, in bytes, of the storage device record. +
+

DESCRIPTION

+

+The default_pager_add_segment 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 default_pager_backing_store_create, 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). +

RETURN VALUES

+
+

+

KERN_FAILURE +
+The default pager does not support this operation. +

+

KERN_INVALID_ARGUMENT +
+The backing_store port does not represent a valid backing store or the +specified segment overlaps an existing partition. +

+

KERN_RESOURCE_SHORTAGE +
+The default pager is unable to allocate internal resources + to manage the new backing storage. +

+

KERN_SUCCESS +
+The operation was successful. +
+

RELATED INFORMATION

+

+Functions: +default_pager_backing_store_create, +default_pager_backing_store_delete, +default_pager_backing_store_info. 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 @@ -

default_pager_info

Server Interface - Furnish caller with information about the pager's paging partition.

SYNOPSIS

kern_return_t   default_pager_info
                (mach_port_t                              pager,
                 default_pager_info_t                      info);


kern_return_t   seqnos_default_pager_info
                (mach_port_t                              pager,
                 mach_port_seqno_t                        seqno,
                 default_pager_info_t                     *info);

PARAMETERS

pager
[in default-pager (receive) right] The default memory manager service port.

seqno
[in scalar] The sequence number of this message relative to the pager port.

info
[out structure] Total and free space consumption.

DESCRIPTION

A default_pager_info 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: vm_set_default_memory_manager, memory_object_default_server, seqnos_memory_object_default_server.

Data Structures: default_pager_info. \ No newline at end of file +

default_pager_info

+
+

+Server Interface - Furnish caller with information about the pager's paging partition. +

SYNOPSIS

+
+kern_return_t   default_pager_info
+                (mach_port_t                              pager,
+                 default_pager_info_t                      info);
+
+
+kern_return_t   seqnos_default_pager_info
+                (mach_port_t                              pager,
+                 mach_port_seqno_t                        seqno,
+                 default_pager_info_t                     *info);
+
+
+

PARAMETERS

+
+

+

pager +
+[in default-pager (receive) right] +The default memory manager service +port. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the pager +port. +

+

info +
+[out structure] +Total and free space consumption. +
+

DESCRIPTION

+

+A default_pager_info 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +vm_set_default_memory_manager, +memory_object_default_server, +seqnos_memory_object_default_server. +

+Data Structures: +default_pager_info. 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 @@ -

device_close

Function - De-establish a connection to a device.

SYNOPSIS

#include< device/device.h>

kern_return_t	device_close
		(mach_port_t	device);

PARAMETERS

device
[in device send right] A device port to the device to be closed.

DESCRIPTION

The device_close 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.

NOTES

device_close will destroy any mapped device windows obtained through this device port.

RETURN VALUES

D_NO_SUCH_DEVICE
No device with that name, or the device is not operational.

RELATED INFORMATION

Functions: device_open. \ No newline at end of file +

device_close

+
+

+Function - De-establish a connection to a device. +

SYNOPSIS

+
+#include< device/device.h>
+
+kern_return_t	device_close
+		(mach_port_t	device);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] +A device port to the device to be closed. +
+

DESCRIPTION

+

+The device_close 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. +

NOTES

+

+device_close will destroy any mapped device windows +obtained through this +device port. +

RETURN VALUES

+
+

+

D_NO_SUCH_DEVICE +
+No device with that name, or the device is not operational. +
+

RELATED INFORMATION

+

+Functions: +device_open. 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 @@ -

device_get_status

Function - Return the current device status.

SYNOPSIS

#include< device/device.h>

kern_return_t   device_get_status
                (mach_port_t                             device,
                 dev_flavor_t                            flavor,
                 dev_status_t                            status,
                 mach_msg_type_number_t           *status_count);

PARAMETERS

device
[in device send right] A device port to the device to be interrogated.

flavor
[in scalar] The type of status information requested.

status
[out array of natural-sized units] The returned device status.

status_count
[pointer to in/out scalar] On input, the reserved size of status; on output, the size of the returned device status (in natural-sized units).

DESCRIPTION

The device_get_status function returns status information pertaining to an open device. The possible values for flavor as well as the meaning of the returned status information is device dependent.

RETURN VALUES

D_DEVICE_DOWN
Device has been shut down

D_NO_SUCH_DEVICE
No device with that name, or the device is not operational.

D_OUT_OF_BAND
Out-of-band condition occurred on device (such as typing \*L-C\*O)

RELATED INFORMATION

Functions: device_set_status. \ No newline at end of file +

device_get_status

+
+

+Function - Return the current device status. +

SYNOPSIS

+
+#include< device/device.h>
+
+kern_return_t   device_get_status
+                (mach_port_t                             device,
+                 dev_flavor_t                            flavor,
+                 dev_status_t                            status,
+                 mach_msg_type_number_t           *status_count);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] +A device port to the device to be interrogated. +

+

flavor +
+[in scalar] +The type of status information requested. +

+

status +
+[out array of natural-sized units] +The returned device status. +

+

status_count +
+[pointer to in/out scalar] +On input, the reserved size of status; on +output, the size of the returned device status (in natural-sized units). +
+

DESCRIPTION

+

+The device_get_status function returns status information +pertaining to an open device. The possible values for flavor as well +as the meaning of the returned status information is device dependent. +

RETURN VALUES

+
+

+

D_DEVICE_DOWN +
+Device has been shut down +

+

D_NO_SUCH_DEVICE +
+No device with that name, or the device is not operational. +

+

D_OUT_OF_BAND +
+Out-of-band condition occurred on device (such as typing \*L-C\*O) +
+

RELATED INFORMATION

+

+Functions: +device_set_status. 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 @@ -

device_map

Function - Establish the specified device's memory manager.

SYNOPSIS

#include< device/device.h>

kern_return_t   device_map
                (mach_port_t                             device,
                 vm_prot_t                                 prot,
                 vm_offset_t                             offset,
                 vm_size_t                                 size,
                 mach_port_t                          mem_obj_t,
                 boolean_t                                unmap);

PARAMETERS

device
[in device send right] A device port to the device to be mapped.

prot
[in scalar] Protection for the device memory.

offset
[in scalar] 15~Offset in memory object.

size
[in scalar] The size of the device memory object.

pager
[out memory-object send right] The returned memory object representative port to a memory manager that represents the device.

unmap
Unused.

DESCRIPTION

The device_map 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 vm_map call. This call is device dependent.

NOTES

Port rights are maintained as follows:

  • Memory object port: the device memory manager has all rights.
  • Memory cache control port: the device memory manager has only send rights.

Regardless of how the object is created, the control port is created by the kernel and passed through the memory management interface.

If the device port used is restricted to use by a single identity, the generated representative port will be likewise restricted.

CAUTIONS

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.

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.

RETURN VALUES

D_DEVICE_DOWN
Device has been shut down

D_NO_SUCH_DEVICE
No device with that name, or the device is not operational.

D_READ_ONLY
Data cannot be written to this device.

RELATED INFORMATION

Functions: vm_map. \ No newline at end of file +

device_map

+
+

+Function - Establish the specified device's memory manager. +

SYNOPSIS

+
+#include< device/device.h>
+
+kern_return_t   device_map
+                (mach_port_t                             device,
+                 vm_prot_t                                 prot,
+                 vm_offset_t                             offset,
+                 vm_size_t                                 size,
+                 mach_port_t                          mem_obj_t,
+                 boolean_t                                unmap);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] +A device port to the device to be mapped. +

+

prot +
+[in scalar] +Protection for the device memory. +

+

offset +
+[in scalar] +15~Offset in memory object. +

+

size +
+[in scalar] +The size of the device memory object. +

+

pager +
+[out memory-object send right] +The returned memory +object representative port to a memory manager that represents the +device. +

+

unmap +
+Unused. +
+

DESCRIPTION

+

+The device_map 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 vm_map call. This call is device dependent. +

NOTES

+

+Port rights are maintained as follows: +

    +
  • +Memory object port: the +device memory manager has all rights. +
  • +Memory cache control port: the device memory manager has only send rights. +
+

+Regardless of how the object is created, the control port is created by +the kernel and passed through the memory management interface. +

+If the device port used is restricted to use by a single identity, +the generated +representative port will be likewise restricted. +

CAUTIONS

+

+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. +

+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. +

RETURN VALUES

+
+

+

D_DEVICE_DOWN +
+Device has been shut down +

+

D_NO_SUCH_DEVICE +
+No device with that name, or the device is not operational. +

+

D_READ_ONLY +
+Data cannot be written to this device. +
+

RELATED INFORMATION

+

+Functions: +vm_map. 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 @@ -

device_open

Function - Establish a connection to a device.

SYNOPSIS

#include<device/device.h>

kern_return_t   device_open
                (mach_port_t                        master_port,
                 mach_port_t                             ledger,
                 dev_mode_t                                mode,
                 security_token_t                   security_id,
                 dev_name_t                                name,
                 mach_port_t                             device);


#include<device/device_request.h>

kern_return_t   device_open_request
                (mach_port_t                        master_port,
                 mach_port_t                         reply_port,
                 mach_port_t                             ledger,
                 dev_mode_t                                mode,
                 security_token_t                   security_id,
                 dev_name_t                                name);


kern_return_t   ds_device_open_reply
                (mach_port_t                         reply_port,
                 kern_return_t                      return_code,
                 mach_port_t                             device);

PARAMETERS

master_port
[in device-master send right] The master device port. This port is provided to the bootstrap task.

reply_port
[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.

ledger
[pointer to a ledger send right] Resource ledger from which the device will draw its resources.

mode
[in scalar] Opening mode. This is the bit-wise OR of the following values:

D_READ
Read access

D_WRITE
Write access

D_NODELAY
Do not delay on open

security_id
[in scalar] The security ID that tasks attempting to use this device port must have. A zero value indicates all identities.

name
[pointer to in array of char] Name of the device to open.

return_code
[in scalar] Status of the open.

device
[out device send right, in for asynchronous form] The returned device port.

DESCRIPTION

The device_open 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 mode. The port is not distinct.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: device_close, device_reply_server. \ No newline at end of file +

device_open

+
+

+Function - Establish a connection to a device. +

SYNOPSIS

+
+#include<device/device.h>
+
+kern_return_t   device_open
+                (mach_port_t                        master_port,
+                 mach_port_t                             ledger,
+                 dev_mode_t                                mode,
+                 security_token_t                   security_id,
+                 dev_name_t                                name,
+                 mach_port_t                             device);
+
+
+#include<device/device_request.h>
+
+kern_return_t   device_open_request
+                (mach_port_t                        master_port,
+                 mach_port_t                         reply_port,
+                 mach_port_t                             ledger,
+                 dev_mode_t                                mode,
+                 security_token_t                   security_id,
+                 dev_name_t                                name);
+
+
+kern_return_t   ds_device_open_reply
+                (mach_port_t                         reply_port,
+                 kern_return_t                      return_code,
+                 mach_port_t                             device);
+
+

PARAMETERS

+
+

+

master_port +
+[in device-master send right] +The master device port. This port is +provided to the bootstrap task. +

+

reply_port +
+[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. +

+

ledger +
+[pointer to a ledger send right] +Resource ledger from which the device will draw its resources. +

+

mode +
+[in scalar] +Opening mode. This is the bit-wise OR of the following +values: +
+

+

D_READ +
+Read access +

+

D_WRITE +
+Write access +

+

D_NODELAY +
+Do not delay on open +
+

+

security_id +
+[in scalar] +The security ID that tasks attempting to use this device port +must have. A zero value indicates all identities. +

+

name +
+[pointer to in array of char] +Name of the device to open. +

+

return_code +
+[in scalar] +Status of the open. +

+

device +
+[out device send right, in for asynchronous form] +The returned device +port. +
+

DESCRIPTION

+

+The device_open 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 mode. The port is not +distinct. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +device_close, +device_reply_server. 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 @@ -

device_read

Function - Read a sequence of bytes from a specific device.

SYNOPSIS

#include<device/device.h>

kern_return_t   device_read
                (device_t                                device,
                 mach_port_t                         reply_port,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_len_t                      bytes_wanted,
                 io_buf_ptr_t                      io_buf_ptr_t,
                 mach_msg_type_number_t  mach_msg_type_number_t);


#include<device/device_request.h>

kern_return_t   device_read_request
                (mach_port_t                            device,
                 mach_port_t                        reply_port,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_len_t                      bytes_wanted);



kern_return_t   ds_device_read_reply
                (mach_port_t                         reply_port,
                 kern_return_t                      return_code,
                 io_buf_ptr_t                              data,
                 mach_msg_type_number_t              data_count);

PARAMETERS

device
[in device send right] A device port to the device to be read.

reply_port
[in reply receive (to be converted to send-once) right] The port to which the reply message is to be sent.

mode
[in scalar] I/O mode value. Meaningful options are:

D_NOWAIT
Do not wait if data is unavailable.

recnum
[in scalar] Record number to be read.

bytes_wanted
[in scalar] Size of data transfer.

return_code
[in scalar] The return status code from the read.

data
[out pointer to dynamic array of bytes, in for asynchronous form] Returned data bytes.

data_count
[out scalar, in for asynchronous form] Number of returned data bytes.

DESCRIPTION

The device_read function reads a sequence of bytes from a device object. The meaning of recnum as well as the specific operation performed is device dependent.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: device_read_inband, device_read_overwrite, device_reply_server. \ No newline at end of file +

device_read

+
+

+Function - Read a sequence of bytes from a specific device. +

SYNOPSIS

+
+#include<device/device.h>
+
+kern_return_t   device_read
+                (device_t                                device,
+                 mach_port_t                         reply_port,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_len_t                      bytes_wanted,
+                 io_buf_ptr_t                      io_buf_ptr_t,
+                 mach_msg_type_number_t  mach_msg_type_number_t);
+
+
+#include<device/device_request.h>
+
+kern_return_t   device_read_request
+                (mach_port_t                            device,
+                 mach_port_t                        reply_port,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_len_t                      bytes_wanted);
+
+
+
+kern_return_t   ds_device_read_reply
+                (mach_port_t                         reply_port,
+                 kern_return_t                      return_code,
+                 io_buf_ptr_t                              data,
+                 mach_msg_type_number_t              data_count);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] +A device port to the device to be read. +

+

reply_port +
+[in reply receive (to be converted to send-once) right] +The port to +which the reply message is to be sent. +

+

mode +
+[in scalar] +I/O mode value. Meaningful options are: +
+

+

D_NOWAIT +
+Do not wait if data is unavailable. +
+

+

recnum +
+[in scalar] +Record number to be read. +

+

bytes_wanted +
+[in scalar] +Size of data transfer. +

+

return_code +
+[in scalar] +The return status code from the read. +

+

data +
+[out pointer to dynamic array of bytes, in for asynchronous form] +Returned data bytes. +

+

data_count +
+[out scalar, in for asynchronous form] +Number of returned data bytes. +
+

DESCRIPTION

+

+The device_read function reads a sequence of bytes +from a device object. The +meaning of recnum as well as the specific operation performed is device +dependent. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +device_read_inband, +device_read_overwrite, +device_reply_server. 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 @@ -

device_read_async

System Trap - Read a sequence of bytes from a device object.

SYNOPSIS

kern_return_t   device_read_async
                (mach_port_t                             device,
                 mach_port_t                              queue,
                 mach_port_t                         request_id,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_len_t                      bytes_wanted);

PARAMETERS

device
[in device send right] A device port to the device to be read.

queue
[in io_done queue send right] The port returned from io_done_queue_create.

request_id
[in send right] An unique request identifier that will be passed back as part of the io_done_result structure.

mode
[in scalar] I/O mode value. Meaningful options are:

D_NOWAIT
Do not wait if data is unavailable.

recnum
[in scalar] Record number to be read.

bytes_wanted
[in scalar] Size of data transfer.

DESCRIPTION

The device_read_async 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.

RETURN VALUES

device_read_async returns only invalid parameter errors.

RELATED INFORMATION

Functions: device_read_async_inband, device_read_overwrite_async, device_write_async, device_write_async_inband, io_done_queue_create. \ No newline at end of file +

device_read_async

+
+

+System Trap - Read a sequence of bytes from a device object. +

SYNOPSIS

+
+kern_return_t   device_read_async
+                (mach_port_t                             device,
+                 mach_port_t                              queue,
+                 mach_port_t                         request_id,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_len_t                      bytes_wanted);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] A device port to the device to be read. +

+

queue +
+[in io_done queue send right] The port returned from +io_done_queue_create. +

+

request_id +
+[in send right] An unique request identifier that will be passed back as +part of the io_done_result structure. +

+

mode +
+[in scalar] I/O mode value. Meaningful options are: +

+

+
D_NOWAIT +
+Do not wait if data is unavailable. +
+

+

recnum +
+[in scalar] Record number to be read. +

+

bytes_wanted +
+[in scalar] Size of data transfer. +
+

DESCRIPTION

+

+The device_read_async 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. +

RETURN VALUES

+
+device_read_async returns only invalid parameter errors. +
+
+

RELATED INFORMATION

+

+Functions: +device_read_async_inband, +device_read_overwrite_async, +device_write_async, +device_write_async_inband, +io_done_queue_create. 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 @@ -

device_read_async_inband

System Trap - Read a sequence of bytes "inband" from a device object.

SYNOPSIS

kern_return_t   device_read_async_inband
                (mach_port_t                             device,
                 mach_port_t                              queue,
                 mach_port_t                         request_id,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_len_t                      bytes_wanted);

PARAMETERS

device
[in device send right] A device port to the device to be read.

queue
[in io_done queue send right] The port returned from io_done_queue_create.

request_id
[in send right] An unique request identifier that will be passed back as part of the io_done_result structure.

mode
[in scalar] I/O mode value. Meaningful options are:

D_NOWAIT
Do not wait if data is unavailable.

recnum
[in scalar] Record number to be read.

bytes_wanted
[in scalar] Size of data transfer.

DESCRIPTION

The device_read_async_inband function 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. This call differs from device_read_async in that the returned bytes are returned "inband" in the completion IPC message (in io_done_result.qd_inline).

RETURN VALUES

device_read_async_inband returns only invalid parameter errors.

RELATED INFORMATION

Functions: device_read_async, device_read_overwrite_async, device_write_async, device_write_async_inband, io_done_queue_create. \ No newline at end of file +

device_read_async_inband

+
+

+System Trap - Read a sequence of bytes "inband" from a device object. +

SYNOPSIS

+
+kern_return_t   device_read_async_inband
+                (mach_port_t                             device,
+                 mach_port_t                              queue,
+                 mach_port_t                         request_id,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_len_t                      bytes_wanted);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] A device port to the device to be read. +

+

queue +
+[in io_done queue send right] The port returned from +io_done_queue_create. +

+

request_id +
+[in send right] An unique request identifier that will be passed back as +part of the io_done_result structure. +

+

mode +
+[in scalar] I/O mode value. Meaningful options are: +

+

+
D_NOWAIT +
+Do not wait if data is unavailable. +
+

+

recnum +
+[in scalar] Record number to be read. +

+

bytes_wanted +
+[in scalar] Size of data transfer. +
+

DESCRIPTION

+

+The device_read_async_inband function 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. This +call differs from device_read_async in that the returned bytes are +returned "inband" in the completion IPC message (in +io_done_result.qd_inline). +

RETURN VALUES

+

+device_read_async_inband returns only invalid parameter errors. +

RELATED INFORMATION

+

+Functions: +device_read_async, +device_read_overwrite_async, +device_write_async, +device_write_async_inband, +io_done_queue_create. 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 @@ -

device_read_inband

Function - Read a sequence of bytes "inband" from a device object.

SYNOPSIS

#include<device/device.h>

kern_return_t   device_read_inband
                (mach_port_t                             device,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_len_t                      bytes_wanted,
                 io_buf_ptr_inband_t                       data,
                 mach_msg_type_number_t             *data_count);


#include<device/device_request.h>

kern_return_t   device_read_request_inband
                (mach_port_t                             device,
                 mach_port_t                         reply_port,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_len_t                      bytes_wanted);


kern_return_t   ds_device_read_reply_inband
                (mach_port_t                         reply_port,
                 kern_return_t                      return_code,
                 io_buf_ptr_inband_t                       data,
                 mach_msg_type_number_t              data_count);

PARAMETERS

device
[in device send right] A device port to the device to be read.

reply_port
[in reply receive (to be converted to send-once) right] The port to which the reply message is to be sent.

mode
[in scalar] I/O mode value. Meaningful options are:

D_NOWAIT
Do not wait if data is unavailable.

recnum
[in scalar] Record number to be read.

bytes_wanted
[in scalar] Size of data transfer.

return_code
[in scalar] The return status code from the read.

data
[out array of bytes, in for asynchronous form] Returned data bytes.

data_count
[out scalar, in for asynchronous form] Number of returned data bytes.

DESCRIPTION

The device_read_inband function reads a sequence of bytes from a device object. The meaning of recnum as well as the specific operation performed is device dependent. This call differs from device_read in that the returned bytes are returned "inband" in the reply IPC message.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: device_read, device_read_overwrite, device_reply_server. \ No newline at end of file +

device_read_inband

+
+

+Function - Read a sequence of bytes "inband" from a device object. +

SYNOPSIS

+
+#include<device/device.h>
+
+kern_return_t   device_read_inband
+                (mach_port_t                             device,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_len_t                      bytes_wanted,
+                 io_buf_ptr_inband_t                       data,
+                 mach_msg_type_number_t             *data_count);
+
+
+#include<device/device_request.h>
+
+kern_return_t   device_read_request_inband
+                (mach_port_t                             device,
+                 mach_port_t                         reply_port,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_len_t                      bytes_wanted);
+
+
+kern_return_t   ds_device_read_reply_inband
+                (mach_port_t                         reply_port,
+                 kern_return_t                      return_code,
+                 io_buf_ptr_inband_t                       data,
+                 mach_msg_type_number_t              data_count);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] +A device port to the device to be read. +

+

reply_port +
+[in reply receive (to be converted to send-once) right] +The port to +which the reply message is to be sent. +

+

mode +
+[in scalar] +I/O mode value. Meaningful options are: +
+

+

D_NOWAIT +
+Do not wait if data is unavailable. +
+

+

recnum +
+[in scalar] +Record number to be read. +

+

bytes_wanted +
+[in scalar] +Size of data transfer. +

+

return_code +
+[in scalar] +The return status code from the read. +

+

data +
+[out array of bytes, in for asynchronous form] +Returned data bytes. +

+

data_count +
+[out scalar, in for asynchronous form] +Number of returned data bytes. +
+

DESCRIPTION

+

+The device_read_inband function reads a sequence of bytes +from a device object. The +meaning of recnum as well as the specific operation performed is device +dependent. This call differs from device_read in that +the returned bytes are returned +"inband" in the reply IPC message. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +device_read, +device_read_overwrite, +device_reply_server. 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 @@ -

device_read_overwrite

System Trap -- Read a sequence of bytes from a specific device into my address space.

SYNOPSIS


kern_return_t   device_read_overwrite
                (mach_port_t                               device,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_len_t                      bytes_wanted,
                 io_buf_pointer_t                          data,
                 mach_msg_type_number_t              data_count);



kern_return_t   device_read_overwrite_request
                (mach_port_t                             device,
                 mach_port_t                         reply_port,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_len_t                      bytes_wanted,
                 io_buf_pointer_t                          data);



kern_return_t   ds_device_read_reply_overwrite
                (mach_port_t                        reply_port,
                 kern_return_t                      return_code,
                 io_buf_len_t                        data_count);

PARAMETERS

device
[in device send right] A device port to the device to be read.

reply_port
[in reply receive (to be converted to send-once) right] The port to which the reply message is to be sent.

mode
[in scalar] I/O mode value. Meaningful options are:

D_NOWAIT
Do not wait if data is unavailable.

recnum
[in scalar] Record number to be read.

bytes_wanted
[in scalar] Size of data transfer.

return_code
[in scalar] The return status code from the read.

data
[pointer to in array of bytes] Data buffer to be overwritten.

data_count
[out scalar, in for asynchronous form] Number of returned data bytes.

DESCRIPTION

The device_read_overwrite system trap reads a sequence of bytes from a device object directly into the caller's address space. The meaning of recnum as well as the specific operation performed is device dependent.

NOTES

The device_read_overwrite_request and device_read_reply_overwrite calls may be removed from the interface in favor of new asynchronous support.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: device_read, device_read_inband, device_reply_server. \ No newline at end of file +

device_read_overwrite

+
+

System Trap -- Read a sequence of bytes from a specific device into my address space. +

SYNOPSIS

+
+
+kern_return_t   device_read_overwrite
+                (mach_port_t                               device,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_len_t                      bytes_wanted,
+                 io_buf_pointer_t                          data,
+                 mach_msg_type_number_t              data_count);
+
+
+
+kern_return_t   device_read_overwrite_request
+                (mach_port_t                             device,
+                 mach_port_t                         reply_port,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_len_t                      bytes_wanted,
+                 io_buf_pointer_t                          data);
+
+
+
+kern_return_t   ds_device_read_reply_overwrite
+                (mach_port_t                        reply_port,
+                 kern_return_t                      return_code,
+                 io_buf_len_t                        data_count);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] +A device port to the device to be read. +

+

reply_port +
+[in reply receive (to be converted to send-once) right] +The port to +which the reply message is to be sent. +

+

mode +
+[in scalar] +I/O mode value. Meaningful options are: +
+

+

D_NOWAIT +
+Do not wait if data is unavailable. +
+

+

recnum +
+[in scalar] +Record number to be read. +

+

bytes_wanted +
+[in scalar] +Size of data transfer. +

+

return_code +
+[in scalar] +The return status code from the read. +

+

data +
+[pointer to in array of bytes] +Data buffer to be overwritten. +

+

data_count +
+[out scalar, in for asynchronous form] +Number of returned data bytes. +
+

DESCRIPTION

+

+The device_read_overwrite system trap reads a sequence +of bytes from a +device object directly into the caller's address space. The +meaning of recnum as +well as the specific operation performed is device dependent. +

NOTES

+

+The device_read_overwrite_request and device_read_reply_overwrite +calls may be removed from the interface in favor of new asynchronous support. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +device_read, +device_read_inband, +device_reply_server. 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 @@ -

device_reply_server

Function - Handle incoming data from kernel device driver.

SYNOPSIS

boolean_t	device_reply_server
		(mach_msg_header_t	request_msg,
		mach_msg_header_t	reply_msg);

PARAMETERS

request_msg
[pointer to in structure] The device driver message received from the kernel.

reply_msg
[out structure] A reply message. No messages from a device driver expect a direct reply, so this field is not used.

DESCRIPTION

The device_reply_server function is the MIG generated server handling function to handle messages from kernel device drivers. Such messages were sent in response to the various device_..._request... 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 device_reply_server function performs all necessary argument handling for a kernel message and calls one of the device server functions to interpret the message.

RETURN VALUES

TRUE
The message was handled and the appropriate function was called.

FALSE
The message did not apply to this device handler interface and no other action was taken.

RELATED INFORMATION

Functions: ds_device_open_reply, ds_device_write_reply, ds_device_write_reply_inband, ds_device_read_reply, ds_device_read_reply_inband, ds_device_read_reply_overwrite. \ No newline at end of file +

device_reply_server

+
+

+Function - Handle incoming data from kernel device driver. +

SYNOPSIS

+
+boolean_t	device_reply_server
+		(mach_msg_header_t	request_msg,
+		mach_msg_header_t	reply_msg);
+
+

PARAMETERS

+
+

+

request_msg +
+[pointer to in structure] +The device driver message received from the +kernel. +

+

reply_msg +
+[out structure] +A reply message. No messages from a device driver +expect a direct reply, so this field is not used. +
+

DESCRIPTION

+

+The device_reply_server function is the MIG generated server handling +function to handle messages from kernel device drivers. Such +messages were sent in response to the various +device_..._request... +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 device_reply_server +function performs all +necessary argument handling for a kernel message and calls one +of the device server functions to interpret the message. +

RETURN VALUES

+
+

+

TRUE +
+The message was handled and the appropriate function was called. +

+

FALSE +
+The message did not apply to this device handler interface and no other +action was taken. +
+

RELATED INFORMATION

+

+Functions: +ds_device_open_reply, +ds_device_write_reply, +ds_device_write_reply_inband, +ds_device_read_reply, +ds_device_read_reply_inband, +ds_device_read_reply_overwrite. 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 @@ -

device_set_filter

Function - Name an input filter for a device.

SYNOPSIS

#include< device/device.h>
#include< device/net_status.h>

kern_return_t   device_set_filter
                (mach_port_t                             device,
                 mach_port_t                       receive_port,
                 mach_msg_type_name_t         receive_port_type,
                 int                                   priority,
                 filter_array_t                          filter,
                 mach_msg_type_number_t             filter_count);

PARAMETERS

device
[in device send right] A device port

receive_port
[in filter send or receive (to be converted to send) right] The port to receive the input data that is selected by the filter.

receive_port_type
[in scalar] IPC type of the send right provided to the device; either MACH_MSG_TYPE_MAKE_SEND, MACH_MSG_TYPE_MOVE_SEND, or MACH_MSG_TYPE_COPY_SEND.

priority
[in scalar] Used to order multiple receivers in an implementation dependent way.

filter
[pointer to in array of filter_t] The address of an array of filter values.

filter_count
[in scalar] The size of the filter array (in 16-bit values).

DESCRIPTION

The device_set_filter 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.

The filter command list consists of an array of up to NET_MAX_FILTER (16-bit) values to be applied to incoming data "messages" to determine if that data should be given to a particular input filter.

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 NETF_NBPO bits) as well as a binary operator (low order NETF_NBPA bits).

The value to be pushed onto the stack is chosen as follows:

NETF_PUSHLIT
Use the next 16-bit value of the filter as the value.
NETF_PUSHZERO
Use 0 as the value.
NETF_PUSHWORD+N
Use 16-bit value N of the "data" portion of the message as the value.
NETF_PUSHHDR+N
Use 16-bit value N of the "header" portion of the message as the value.
NETF_PUSHIND
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.
NETF_PUSHHDRIND
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.
NETF_PUSHSTK+N
Use 32-bit value N of the stack (where the top of stack is value 0) as the value.
NETF_NOPUSH
Don't push a value.
The unsigned value so chosen is promoted to a 32-bit value before being pushed.

Once a value is pushed (except for the case of NETF_NOPUSH), 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:

NETF_NOP
Don't pop off any values and do no operation.
NETF_EQ
Perform an equal comparison.
NETF_LT
Perform a less than comparison.
NETF_LE
Perform a less than or equal comparison.
NETF_GT
Perform a greater than comparison.
NETF_GE
Perform a greater than or equal comparison.
NETF_AND
Perform a bit-wise boolean AND operation.
NETF_OR
Perform a bit-wise boolean inclusive OR operation.
NETF_XOR
Perform a bit-wise boolean exclusive OR operation.
NETF_NEQ
Perform a not equal comparison.
NETF_LSH
Perform a left shift operation.
NETF_RSH
Perform a right shift operation.
NETF_ADD
Perform an addition.
NETF_SUB
Perform a subtraction.
NETF_COR
Perform an equal comparison. If the comparison is TRUE, terminate the filter list. Otherwise, pop the result of the comparison off the stack.
NETF_CAND
Perform an equal comparison. If the comparison is FALSE, terminate the filter list. Otherwise, pop the result of the comparison off the stack.
NETF_CNOR
Perform a not equal comparison. If the comparison is FALSE, terminate the filter list. Otherwise, pop the result of the comparison off the stack.
NETF_CNAND
Perform a not equal comparison. If the comparison is TRUE, terminate the filter list. Otherwise, pop the result of the comparison off the stack.
The scan of the filter list terminates when the filter list is emptied, or a NETF_C operation terminates the list. At this time, if the final value of the top of the stack is TRUE, then the message is accepted for the filter.

RETURN VALUES

D_DEVICE_DOWN
Device has been shut down

D_INVALID_OPERATION
No filter port was supplied.

D_NO_SUCH_DEVICE
No device with that name, or the device is not operational.

RELATED INFORMATION

Currently no references. \ No newline at end of file +

device_set_filter

+
+

+Function - Name an input filter for a device. +

SYNOPSIS

+
+#include< device/device.h>
+#include< device/net_status.h>
+
+kern_return_t   device_set_filter
+                (mach_port_t                             device,
+                 mach_port_t                       receive_port,
+                 mach_msg_type_name_t         receive_port_type,
+                 int                                   priority,
+                 filter_array_t                          filter,
+                 mach_msg_type_number_t             filter_count);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] +A device port +

+

receive_port +
+[in filter send or receive (to be converted to send) right] +The port to +receive the input data that is selected by the filter. +

+

receive_port_type +
+[in scalar] +IPC type of the send right provided to the device; either +MACH_MSG_TYPE_MAKE_SEND, MACH_MSG_TYPE_MOVE_SEND, +or MACH_MSG_TYPE_COPY_SEND. +

+

priority +
+[in scalar] +Used to order multiple receivers in an implementation +dependent way. +

+

filter +
+[pointer to in array of filter_t] +The address of an array of filter values. +

+

filter_count +
+[in scalar] +The size of the filter array (in 16-bit values). +
+

DESCRIPTION

+

+The device_set_filter 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. +

+The filter command list consists of an array of up to NET_MAX_FILTER +(16-bit) values to be applied to incoming data "messages" to determine if +that data should be given to a particular input filter. +

+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 NETF_NBPO +bits) as well as a binary operator (low order NETF_NBPA bits). +

+The value to be pushed onto the stack is chosen as follows: +

+
NETF_PUSHLIT +
+Use the next 16-bit value of the filter as the value. +
NETF_PUSHZERO +
+Use 0 as the value. +
NETF_PUSHWORD+N +
+Use 16-bit value N of the "data" portion of the message as the value. +
NETF_PUSHHDR+N +
+Use 16-bit value N of the "header" portion of the message as the value. +
NETF_PUSHIND +
+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. +
NETF_PUSHHDRIND +
+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. +
NETF_PUSHSTK+N +
+Use 32-bit value N of the stack (where the top of stack is value 0) as +the value. +
NETF_NOPUSH +
+Don't push a value. +
+The unsigned value so chosen is promoted to a 32-bit value before being pushed. +

+Once a value is pushed (except for the case of NETF_NOPUSH), 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: +

+
NETF_NOP +
+Don't pop off any values and do no operation. +
NETF_EQ +
+Perform an equal comparison. +
NETF_LT +
+Perform a less than comparison. +
NETF_LE +
+Perform a less than or equal comparison. +
NETF_GT +
+Perform a greater than comparison. +
NETF_GE +
+Perform a greater than or equal comparison. +
NETF_AND +
+Perform a bit-wise boolean AND operation. +
NETF_OR +
+Perform a bit-wise boolean inclusive OR operation. +
NETF_XOR +
+Perform a bit-wise boolean exclusive OR operation. +
NETF_NEQ +
+Perform a not equal comparison. +
NETF_LSH +
+Perform a left shift operation. +
NETF_RSH +
+Perform a right shift operation. +
NETF_ADD +
+Perform an addition. +
NETF_SUB +
+Perform a subtraction. +
NETF_COR +
+Perform an equal comparison. If the comparison is TRUE, terminate +the filter list. Otherwise, pop the result of the comparison off the stack. +
NETF_CAND +
+Perform an equal comparison. If the comparison is FALSE, terminate +the filter list. Otherwise, pop the result of the comparison off the stack. +
NETF_CNOR +
+Perform a not equal comparison. If the comparison is FALSE, +terminate the filter list. Otherwise, pop the result of the +comparison off the +stack. +
NETF_CNAND +
+Perform a not equal comparison. If the comparison is TRUE, terminate +the filter list. Otherwise, pop the result of the comparison off the stack. +
+The scan of the filter list terminates when the filter list is emptied, or a +NETF_C operation terminates the list. At this time, if the final +value of the top of the stack is TRUE, then the message is accepted +for the filter. +

RETURN VALUES

+
+

+

D_DEVICE_DOWN +
+Device has been shut down +

+

D_INVALID_OPERATION +
+No filter port was supplied. +

+

D_NO_SUCH_DEVICE +
+No device with that name, or the device is not operational. +
+

RELATED INFORMATION

+

+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 @@ -

device_set_status

Function - Set device status.

SYNOPSIS

#include< device/device.h>

kern_return_t   device_set_status
                (mach_port_t                             device,
                 dev_flavor_t                            flavor,
                 dev_status_t                            status,
                 mach_msg_type_number_t            status_count);

PARAMETERS

device
[in device send right] A device port to the device to be manipulated.

flavor
[in scalar] The type of status information to set.

status
[pointer to in array of natural-sized units] The status information to set.

status_count
[in scalar] The size of the status information (in natural-sized units).

DESCRIPTION

The device_set_status function sets device status. The possible values of flavor as well as the corresponding meanings are device dependent.

RETURN VALUES

D_DEVICE_DOWN
Device has been shut down

D_IO_ERROR
Hardware I/O error

D_NO_SUCH_DEVICE
No device with that name, or the device is not operational.

D_OUT_OF_BAND
Out-of-band condition occurred on device (such as typing <Ctrl>-C).

D_READ_ONLY
Data cannot be written to this device.

RELATED INFORMATION

Functions: device_get_status. \ No newline at end of file +

device_set_status

+
+

+Function - Set device status. +

SYNOPSIS

+
+#include< device/device.h>
+
+kern_return_t   device_set_status
+                (mach_port_t                             device,
+                 dev_flavor_t                            flavor,
+                 dev_status_t                            status,
+                 mach_msg_type_number_t            status_count);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] +A device port to the device to be manipulated. +

+

flavor +
+[in scalar] +The type of status information to set. +

+

status +
+[pointer to in array of natural-sized units] +The status information to set. +

+

status_count +
+[in scalar] +The size of the status information (in natural-sized units). +
+

DESCRIPTION

+

+The device_set_status function sets device status. +The possible values of flavor +as well as the corresponding meanings are device dependent. +

RETURN VALUES

+
+

+

D_DEVICE_DOWN +
+Device has been shut down +

+

D_IO_ERROR +
+Hardware I/O error +

+

D_NO_SUCH_DEVICE +
+No device with that name, or the device is not operational. +

+

D_OUT_OF_BAND +
+Out-of-band condition occurred on device (such as typing + <Ctrl>-C). +

+

D_READ_ONLY +
+Data cannot be written to this device. +
+

RELATED INFORMATION

+

+Functions: +device_get_status. 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 @@ -

device_write

Function - Write a sequence of bytes to a specific device.

SYNOPSIS

#include<device/device.h>

kern_return_t   device_write
                (device_t                                device,
                 mach_port_t                         reply_port,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_ptr_t                              data,
                 mach_msg_type_number_t              data_count,
                 io_buf_len_t                      io_buf_len_t);


#include<device/device_request.h>

kern_return_t   device_write_request
                (mach_port_t                             device,
                 mach_port_t                         reply_port,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_ptr_t                              data,
                 mach_msg_type_number_t              data_count);


kern_return_t   ds_device_write_reply
                (mach_port_t                         reply_port,
                 kern_return_t                      return_code,
                 io_buf_len_t                     bytes_written);

PARAMETERS

device
[in device send right] A device port to the device to be written.

reply_port
[in reply receive (to be converted to send-once) right] The port to which the reply message is to be sent.

mode
[in scalar] I/O mode value. Meaningful options are:

D_NOWAIT
Do not wait for I/O completion.

recnum
[in scalar] Record number to be written.

data
[pointer to in array of bytes] Data bytes to be written.

data_count
[in scalar] Number of data bytes to be written.

return_code
[in scalar] The return status code from the write.

bytes_written
[out scalar, in for asynchronous form] Size of data transfer.

DESCRIPTION

The device_write function writes a sequence of bytes to a device object. The meaning of recnum as well as the specific operation performed is device dependent.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: device_write_inband, device_reply_server. \ No newline at end of file +

device_write

+
+

+Function - Write a sequence of bytes to a specific device. +

SYNOPSIS

+
+#include<device/device.h>
+
+kern_return_t   device_write
+                (device_t                                device,
+                 mach_port_t                         reply_port,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_ptr_t                              data,
+                 mach_msg_type_number_t              data_count,
+                 io_buf_len_t                      io_buf_len_t);
+
+
+#include<device/device_request.h>
+
+kern_return_t   device_write_request
+                (mach_port_t                             device,
+                 mach_port_t                         reply_port,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_ptr_t                              data,
+                 mach_msg_type_number_t              data_count);
+
+
+kern_return_t   ds_device_write_reply
+                (mach_port_t                         reply_port,
+                 kern_return_t                      return_code,
+                 io_buf_len_t                     bytes_written);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] +A device port to the device to be written. +

+

reply_port +
+[in reply receive (to be converted to send-once) right] +The port to +which the reply message is to be sent. +

+

mode +
+[in scalar] +I/O mode value. Meaningful options are: +
+

+

D_NOWAIT +
+Do not wait for I/O completion. +
+

+

recnum +
+[in scalar] +Record number to be written. +

+

data +
+[pointer to in array of bytes] +Data bytes to be written. +

+

data_count +
+[in scalar] +Number of data bytes to be written. +

+

return_code +
+[in scalar] +The return status code from the write. +

+

bytes_written +
+[out scalar, in for asynchronous form] +Size of data transfer. +
+

DESCRIPTION

+

+The device_write function writes a sequence of bytes +to a device object. The +meaning of recnum as well as the specific operation performed is device +dependent. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +device_write_inband, +device_reply_server. 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 @@ -

device_write_async

System Trap - Write a sequence of bytes to a device object.

SYNOPSIS

kern_return_t   device_write_async
                (mach_port_t                             device,
                 mach_port_t                              queue,
                 mach_port_t                         request_id,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_ptr_t                              data,
                 io_buf_len_t                      bytes_wanted);

PARAMETERS

device
[in device send right] A device port to the device to be read.

queue
[in io_done queue send right] The port returned from io_done_queue_create.

request_id
[in send right] An unique request identifier that will be passed back as part of the io_done_result structure.

mode
[in scalar] I/O mode value. Meaningful options are:

D_NOWAIT
Do not wait if data is unavailable.

recnum
[in scalar] Record number to be read.

data
[pointer to in array of bytes] Data bytes to be written.

bytes_wanted
[in scalar] Size of data transfer.

DESCRIPTION

The device_write_async 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.

RETURN VALUES

device_write_async returns only invalid parameter errors.

RELATED INFORMATION

Functions: device_read_async_inband, device_read_overwrite_async, device_write_async_inband, io_done_queue_create. \ No newline at end of file +

device_write_async

+
+

+System Trap - Write a sequence of bytes to a device object. +

SYNOPSIS

+
+kern_return_t   device_write_async
+                (mach_port_t                             device,
+                 mach_port_t                              queue,
+                 mach_port_t                         request_id,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_ptr_t                              data,
+                 io_buf_len_t                      bytes_wanted);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] A device port to the device to be read. +

+

queue +
+[in io_done queue send right] The port returned from +io_done_queue_create. +

+

request_id +
+[in send right] An unique request identifier that will be passed back as +part of the io_done_result structure. +

+

mode +
+[in scalar] I/O mode value. Meaningful options are: +

+

+
D_NOWAIT +
+Do not wait if data is unavailable. +
+

+

recnum +
+[in scalar] Record number to be read. +

+

data +
+[pointer to in array of bytes] Data bytes to be written. +

+

bytes_wanted +
+[in scalar] Size of data transfer. +
+

DESCRIPTION

+

+The device_write_async 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. +

RETURN VALUES

+

+device_write_async returns only invalid parameter errors. +

RELATED INFORMATION

+

+Functions: +device_read_async_inband, +device_read_overwrite_async, +device_write_async_inband, +io_done_queue_create. 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 @@ -

device_write_async_inband

System Trap - Write a sequence of bytes "inband" to a device object.

SYNOPSIS

kern_return_t   device_write_async_inband
                (mach_port_t                             device,
                 mach_port_t                              queue,
                 mach_port_t                         request_id,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_ptr_t                              data,
                 io_buf_len_t                      bytes_wanted);

PARAMETERS

device
[in device send right] A device port to the device to be read.

queue
[in io_done queue send right] The port returned from io_done_queue_create.

request_id
[in send right] An unique request identifier that will be passed back as part of the io_done_result structure.

mode
[in scalar] I/O mode value. Meaningful options are:

D_NOWAIT
Do not wait if data is unavailable.

recnum
[in scalar] Record number to be read.

data
[pointer to in array of bytes] Data bytes to be written.

bytes_wanted
[in scalar] Size of data transfer.

DESCRIPTION

The device_write_async_inband 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 device_write_async in that the bytes to be written are sent "inband" in the request IPC message.

RETURN VALUES

device_write_async_inband returns only invalid parameter errors.

RELATED INFORMATION

Functions: device_read_async_inband, device_read_overwrite_async, device_write_async, io_done_queue_create. \ No newline at end of file +

device_write_async_inband

+
+

+System Trap - Write a sequence of bytes "inband" to a device object. +

SYNOPSIS

+
+kern_return_t   device_write_async_inband
+                (mach_port_t                             device,
+                 mach_port_t                              queue,
+                 mach_port_t                         request_id,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_ptr_t                              data,
+                 io_buf_len_t                      bytes_wanted);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] A device port to the device to be read. +

+

queue +
+[in io_done queue send right] The port returned from +io_done_queue_create. +

+

request_id +
+[in send right] An unique request identifier that will be passed back as +part of the io_done_result structure. +

+

mode +
+[in scalar] I/O mode value. Meaningful options are: +

+

+
D_NOWAIT +
+Do not wait if data is unavailable. +
+

+

recnum +
+[in scalar] Record number to be read. +

+

data +
+[pointer to in array of bytes] Data bytes to be written. +

+

bytes_wanted +
+[in scalar] Size of data transfer. +
+

DESCRIPTION

+

+The device_write_async_inband 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 device_write_async in that the bytes to be written +are sent "inband" in the request IPC message. +

RETURN VALUES

+

+device_write_async_inband returns only invalid parameter errors. +

RELATED INFORMATION

+

+Functions: +device_read_async_inband, +device_read_overwrite_async, +device_write_async, +io_done_queue_create. 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 @@ -

device_write_inband

Function - Write a sequence of bytes "inband" to a device object.

SYNOPSIS

#include<device/device.h (device_write_inband)>

kern_return_t   device_write_inband
                (mach_port_t                             device,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_ptr_inband_t                       data,
                 mach_msg_type_number_t              data_count,
                 io_buf_len_t                      io_buf_len_t);


#include<device/device_request.h>

kern_return_t   device_write_request_inband
                (mach_port_t                             device,
                 mach_port_t                         reply_port,
                 dev_mode_t                                mode,
                 recnum_t                                recnum,
                 io_buf_ptr_inband_t                       data,
                 mach_msg_type_number_t              data_count);


kern_return_t   ds_device_write_reply_inband
                (mach_port_t                         reply_port,
                 kern_return_t                      return_code,
                 io_buf_len_t                      bytes_writte);

PARAMETERS

device
[in device send right] A device port to the device to be written.

reply_port
[in reply receive (to be converted to send-once) right] The port to which the reply message is to be sent.

mode
[in scalar] I/O mode value. Meaningful options are:

D_NOWAIT
Do not wait for I/O completion.

recnum
[in scalar] Record number to be written.

data
[pointer to in array of bytes] Data bytes to be written.

data_count
[in scalar] Number of data bytes to be written.

return_code
[in scalar] The return status code from the write.

bytes_written
[out scalar, in for asynchronous form] Size of data transfer.

DESCRIPTION

The device_write_inband function writes 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 device_write in that the bytes to be written are sent "inband" in the request IPC message.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: device_write, device_reply_server. \ No newline at end of file +

device_write_inband

+
+

+Function - Write a sequence of bytes "inband" to a device object. +

SYNOPSIS

+
+#include<device/device.h (device_write_inband)>
+
+kern_return_t   device_write_inband
+                (mach_port_t                             device,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_ptr_inband_t                       data,
+                 mach_msg_type_number_t              data_count,
+                 io_buf_len_t                      io_buf_len_t);
+
+
+#include<device/device_request.h>
+
+kern_return_t   device_write_request_inband
+                (mach_port_t                             device,
+                 mach_port_t                         reply_port,
+                 dev_mode_t                                mode,
+                 recnum_t                                recnum,
+                 io_buf_ptr_inband_t                       data,
+                 mach_msg_type_number_t              data_count);
+
+
+kern_return_t   ds_device_write_reply_inband
+                (mach_port_t                         reply_port,
+                 kern_return_t                      return_code,
+                 io_buf_len_t                      bytes_writte);
+
+

PARAMETERS

+
+

+

device +
+[in device send right] +A device port to the device to be written. +

+

reply_port +
+[in reply receive (to be converted to send-once) right] +The port to +which the reply message is to be sent. +

+

mode +
+[in scalar] +I/O mode value. Meaningful options are: +
+

+

D_NOWAIT +
+Do not wait for I/O completion. +
+

+

recnum +
+[in scalar] +Record number to be written. +

+

data +
+[pointer to in array of bytes] +Data bytes to be written. +

+

data_count +
+[in scalar] +Number of data bytes to be written. +

+

return_code +
+[in scalar] +The return status code from the write. +

+

bytes_written +
+[out scalar, in for asynchronous form] +Size of data transfer. +
+

DESCRIPTION

+

+The device_write_inband function writes 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 device_write +in that the bytes to be written are sent "inband" in the request IPC message. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +device_write, +device_reply_server. 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 @@ -

do_mach_notify_dead_name

Server Interface - Handle the current instance of a dead-name notification.

SYNOPSIS

kern_return_t   do_mach_notify_dead_name
                (notify_port_t                           notify,
                 mach_port_name_t                          name);


kern_return_t   do_seqnos_mach_notify_dead_name
                (notify_port_t                           notify,
                 mach_port_seqno_t                        seqno,
                 mach_port_name_t                          name);

PARAMETERS

notify
[in notify (receive) right] The port to which the notification was sent.

seqno
[in scalar] The sequence number of this message relative to the notification port.

name
[in scalar] The dead name.

DESCRIPTION

A do_mach_notify_dead_name function is called by notify_server 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. notify is the port named via mach_port_request_notification or mach_msg.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: notify_server, seqnos_notify_server, mach_msg, mach_port_request_notification, do_mach_notify_no_senders, do_mach_notify_port_deleted, do_mach_notify_send_once. \ No newline at end of file +

do_mach_notify_dead_name

+
+Server Interface - Handle the current instance of a dead-name notification. +

+

SYNOPSIS

+
+kern_return_t   do_mach_notify_dead_name
+                (notify_port_t                           notify,
+                 mach_port_name_t                          name);
+
+
+kern_return_t   do_seqnos_mach_notify_dead_name
+                (notify_port_t                           notify,
+                 mach_port_seqno_t                        seqno,
+                 mach_port_name_t                          name);
+
+

PARAMETERS

+
+

+

notify +
+[in notify (receive) right] +The port to which the notification was sent. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the +notification port. +

+

name +
+[in scalar] +The dead name. +
+

DESCRIPTION

+

+A do_mach_notify_dead_name function is called by notify_server +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. notify is the port named via mach_port_request_notification +or +mach_msg. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +notify_server, +seqnos_notify_server, +mach_msg, +mach_port_request_notification, +do_mach_notify_no_senders, +do_mach_notify_port_deleted, +do_mach_notify_send_once. 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 @@ -

do_mach_notify_no_senders

Server Interface - Handle the current instance of a no-more-senders notification.

SYNOPSIS

kern_return_t   do_mach_notify_no_senders
                (notify_port_t                           notify,
                 mach_port_mscount_t                    mscount);


kern_return_t   do_seqnos_mach_notify_no_senders
                (notify_port_t                           notify,
                 mach_port_seqno_t                        seqno,
                 mach_port_mscount_t                    mscount);

PARAMETERS

notify
[in notify (receive) right] The port to which the notification was sent.

seqno
[in scalar] The sequence number of this message relative to the notification port.

mscount
[in scalar] The value the port's make-send count had when the notification was generated.

DESCRIPTION

A do_mach_notify_no_senders function is called by notify_server as the result of a kernel message indicating that a receive right has no more senders. notify is the port named via mach_port_request_notification.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: notify_server, seqnos_notify_server, mach_msg, mach_port_request_notification, do_mach_notify_dead_name, do_mach_notify_port_deleted, do_mach_notify_send_once. \ No newline at end of file +

do_mach_notify_no_senders

+
+

+Server Interface - Handle the current instance of a no-more-senders notification. +

SYNOPSIS

+
+kern_return_t   do_mach_notify_no_senders
+                (notify_port_t                           notify,
+                 mach_port_mscount_t                    mscount);
+
+
+kern_return_t   do_seqnos_mach_notify_no_senders
+                (notify_port_t                           notify,
+                 mach_port_seqno_t                        seqno,
+                 mach_port_mscount_t                    mscount);
+
+

PARAMETERS

+
+

+

notify +
+[in notify (receive) right] +The port to which the notification was sent. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the +notification port. +

+

mscount +
+[in scalar] +The value the port's make-send count had when the +notification was generated. +
+

DESCRIPTION

+

+A do_mach_notify_no_senders function is called by +notify_server as the +result of a kernel message indicating that a receive right has no more senders. +notify is the port named via mach_port_request_notification. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +notify_server, +seqnos_notify_server, +mach_msg, +mach_port_request_notification, +do_mach_notify_dead_name, +do_mach_notify_port_deleted, +do_mach_notify_send_once. 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 @@ -

do_mach_notify_send_once

Server Interface - Handle the current instance of a send-once notification.

SYNOPSIS

kern_return_t   do_mach_notify_send_once
                (notify_port_t                          notify)


kern_return_t   do_seqnos_mach_notify_send_once
                (notify_port_t                           notify,
                 mach_port_seqno_t                        seqno);

PARAMETERS

notify
[in notify (receive) right] The port to which the notification was sent.

seqno
[in scalar] The sequence number of this message relative to the notification port.

DESCRIPTION

A do_mach_notify_send_once function is called by notify_server as the result of a kernel message indicating that a send-once right was in any way destroyed. notify is the port for which a send-once right was destroyed.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: notify_server, seqnos_notify_server, mach_msg, mach_port_request_notification, do_mach_notify_no_senders, do_mach_notify_port_deleted, do_mach_notify_dead_name. \ No newline at end of file +

do_mach_notify_send_once

+
+

+Server Interface - Handle the current instance of a send-once notification. +

SYNOPSIS

+
+kern_return_t   do_mach_notify_send_once
+                (notify_port_t                          notify)
+
+
+kern_return_t   do_seqnos_mach_notify_send_once
+                (notify_port_t                           notify,
+                 mach_port_seqno_t                        seqno);
+
+

PARAMETERS

+
+

+

notify +
+[in notify (receive) right] +The port to which the notification was sent. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the +notification port. +
+

DESCRIPTION

+

+A do_mach_notify_send_once function is called by notify_server +as the result +of a kernel message indicating that a send-once right was in +any way destroyed. +notify is the port for which a send-once right was destroyed. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +notify_server, +seqnos_notify_server, +mach_msg, +mach_port_request_notification, +do_mach_notify_no_senders, +do_mach_notify_port_deleted, +do_mach_notify_dead_name. 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 @@ -

etap_get_info

Function - Map ETAP buffers and tables into server's address space.

SYNOPSIS

#include<mach/etap.h>

kern_return_t   etap_get_info
                (host_priv_t                          priv_port,
                 int                                        int,
                 int                                        int,
                 vm_offset_t                        vm_offset_t,
                 vm_offset_t                        vm_offset_t,
                 int                                        int,
                 int                                        int,
                 int                                        int,
                 int                                        int);

PARAMETERS

priv_port
the name of the Server's privileged device port (server_device_port), granting the Server access to this service.

et_entries
used to return number of entries in the event table.

st_entries
used to return number of entries in the subsystem table.

et_offset
used to return the event table's page offset.

st_offset
used to return the subsystem table's page offset.

cb_width
returns the current cumulative buffer interval width.

mb_size
returns the size of the monitored buffers,

mb_entries
returns the maximum number of entries in a monitored buffer.

mb_cpus
returns the number of allocated monitored buffers (or supported CPUs).

DESCRIPTION

The etap_get_info 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: 

    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

The values between the brackets correspond with the arguments returned by the etap_get_info 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.

RETURN VALUES

KERN_SUCCESS
The call was performed successfully.

RELATED INFORMATION

Functions: etap_probe, etap_trace_thread, etap_trace_event, etap_get_info. \ No newline at end of file +

etap_get_info

+
+

+Function - Map ETAP buffers and tables into server's address space. +

SYNOPSIS

+
+#include<mach/etap.h>
+
+kern_return_t   etap_get_info
+                (host_priv_t                          priv_port,
+                 int                                        int,
+                 int                                        int,
+                 vm_offset_t                        vm_offset_t,
+                 vm_offset_t                        vm_offset_t,
+                 int                                        int,
+                 int                                        int,
+                 int                                        int,
+                 int                                        int);
+
+

PARAMETERS

+
+

+

priv_port +
+the name of the Server's privileged device port (server_device_port), + granting the Server access to this service. +

+

et_entries +
+used to return number of entries in the event table. +

+

st_entries +
+used to return number of entries in the subsystem table. +

+

et_offset +
+used to return the event table's page offset. +

+

st_offset +
+used to return the subsystem table's page offset. +

+

cb_width +
+returns the current cumulative buffer interval width. +

+

mb_size +
+returns the size of the monitored buffers, +

+

mb_entries +
+returns the maximum number of entries in a monitored buffer. +

+

mb_cpus +
+returns the number of allocated monitored buffers (or supported CPUs). +
+

DESCRIPTION

+

+The etap_get_info 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: +

+    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
+
+

+The values between the brackets correspond with the arguments returned +by the etap_get_info 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. +

RETURN VALUES

+
+
KERN_SUCCESS +
+ The call was performed successfully. +
+

RELATED INFORMATION

+

+Functions: +etap_probe, +etap_trace_thread, +etap_trace_event, +etap_get_info. 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 @@ -

etap_probe

System Trap - Record event data in the kernel's ETAP buffer(s).

SYNOPSIS

#include<mach/etap.h>

kern_return_t   etap_probe
                (int                                   event_id,
                 event_id                             data_size,
                 etap_data_t                        etap_data_t);

PARAMETERS

event_id
A user defined value used to identify the event.

data_size
The size (in bytes) of the data being passed. Note: The data size is limited to ETAP_DATA_SIZE, (defined in mach/etap.h).

data
A pointer to the event data being passed.

DESCRIPTION

Application programmers may instrument their applications with user-level probes, using the etap_probe system call. All event data passed to the kernel via etap_probe is recorded in the kernel's ETAP monitored buffer(s). Each record includes a time stamp.

RETURN VALUES

KERN_SUCCESS
The call was performed successfully.

KERN_INVALID_ARGUMENT
The specified data size exceeds ETAP_DATA_SIZE.

KERN_NO_ACCESS
The tracing of user events is currently enabled.

KERN_FAILURE
ETAP is not configured in the kernel.

RELATED INFORMATION

Functions: etap_trace_thread, etap_trace_event, etap_get_info. \ No newline at end of file +

etap_probe

+
+

+System Trap - Record event data in the kernel's +ETAP buffer(s). +

SYNOPSIS

+
+#include<mach/etap.h>
+
+kern_return_t   etap_probe
+                (int                                   event_id,
+                 event_id                             data_size,
+                 etap_data_t                        etap_data_t);
+
+

PARAMETERS

+
+

+

event_id +
+A user defined value used to identify the event. +

+

data_size +
+The size (in bytes) of the data being passed. +Note: The data size is limited to ETAP_DATA_SIZE, +(defined in mach/etap.h). +

+

data +
+A pointer to the event data being passed. +
+

DESCRIPTION

+

+Application programmers may instrument their applications with +user-level probes, using the +etap_probe system call. All +event data passed to the kernel via +etap_probe is recorded in the +kernel's ETAP monitored buffer(s). Each record includes a time stamp. +

RETURN VALUES

+
+
KERN_SUCCESS +
+ The call was performed successfully. +

+

KERN_INVALID_ARGUMENT +
+ The specified data size exceeds ETAP_DATA_SIZE. +

+

KERN_NO_ACCESS +
+ The tracing of user events is currently enabled. +

+

KERN_FAILURE +
+ ETAP is not configured in the kernel. +
+

RELATED INFORMATION

+

+Functions: +etap_trace_thread, +etap_trace_event, +etap_get_info. 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 @@ -

etap_trace_event

System Trap - manipulate event probes and lock event tracing.

SYNOPSIS

#include<mach/etap.h>

kern_return_t   etap_trace_event
                (etap_data_t                               mode,
                 mode                                      type,
                 boolean_t                               enable,
                 enable                                   nargs,
                 mode                                      mode);

PARAMETERS

mode
indicates the desired trace flavor or reset option and may be one, or more, of the following:

  • ETAP_CUMULATIVE: cumulative lock event trace mode.

  • ETAP_MONITORED: monitored event trace mode (for probes or locks)

  • ETAP_RESET: reset mode, clears all trace status and cumulative buffer entries

type
used when measuring lock event contention or durations and may be one, or more, of the following:

  • ETAP_CONTENT

  • ETAP_DURATION

enable
a boolean value indicattin whether the event trace operation is to be enabled (TRUE) or disabled (FALSE).

nargs
specifies how many arguments are passed in the args array.

args
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 mach/etap.h).

DESCRIPTION

The etap_trace_event 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 nargs parameter.

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 nargs 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: 

         etap_trace_event(ETAP_RESET, 0, 0, 100, 0);

RETURN VALUES

KERN_SUCCESS
The call was performed successfully.

KERN_NO_SPACE
A shortage of kernel resources prevented the operation from completing; the kernel has cleaned up all residual state (the error indicates a "clean" failure).

KERN_FAILURE
ETAP is not configured in the kernel.

RELATED INFORMATION

Functions: etap_probe, etap_trace_thread, etap_get_info. \ No newline at end of file +

etap_trace_event

+
+

+System Trap - +manipulate event probes and lock event tracing. +

SYNOPSIS

+
+#include<mach/etap.h>
+
+kern_return_t   etap_trace_event
+                (etap_data_t                               mode,
+                 mode                                      type,
+                 boolean_t                               enable,
+                 enable                                   nargs,
+                 mode                                      mode);
+
+

PARAMETERS

+
+

+

mode +
+indicates the desired trace flavor or reset option and may be one, +or more, of the following: +
    +

    +

  • +ETAP_CUMULATIVE: cumulative lock event trace mode. +

    +

  • +ETAP_MONITORED: monitored event trace mode (for probes or locks) +

    +

  • +ETAP_RESET: reset mode, clears all trace status and cumulative buffer entries +
+

+

type +
+used when measuring lock event contention or durations +and may be one, or more, of the following: +
    +

    +

  • +ETAP_CONTENT +

    +

  • +ETAP_DURATION +
+

+

enable +
+a boolean value indicattin whether the event trace operation is +to be enabled (TRUE) or disabled (FALSE). +

+

nargs +
+specifies how many arguments are passed in the args array. +

+

args +
+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 mach/etap.h). +
+

DESCRIPTION

+

+The etap_trace_event 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 nargs parameter. +

+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 nargs 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: +

+         etap_trace_event(ETAP_RESET, 0, 0, 100, 0);
+
+
+

RETURN VALUES

+
+
KERN_SUCCESS +
+ The call was performed successfully. +

+

KERN_NO_SPACE +
+ A shortage of kernel resources prevented the operation from completing; + the kernel has cleaned up all residual state (the error indicates a "clean" + failure). +

+

KERN_FAILURE +
+ ETAP is not configured in the kernel. +
+

RELATED INFORMATION

+

+Functions: +etap_probe, +etap_trace_thread, +etap_get_info. 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 @@ -

etap_trace_thread

Function - Set a thread's ETAP trace status.

SYNOPSIS

#include<mach/etap.h>

kern_return_t   etap_trace_thread
                (thread_act_t                     target_thread,
                 boolean_t                               active);

PARAMETERS

target_thread
The port of the thread who's ETAP trace status will be toggled.

active
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.

DESCRIPTION

The etap_trace_thread system call is used to toggle the ETAP trace status of a thread.

RETURN VALUES

KERN_SUCCESS
The call was performed successfully.

KERN_INVALID_ARGUMENT
The value of target_thread does not name a valid thread.

KERN_FAILURE
ETAP is not configured in the kernel.

RELATED INFORMATION

Functions: etap_probe, etap_trace_event, etap_get_info. \ No newline at end of file +

etap_trace_thread

+
+

+Function - Set a thread's ETAP trace status. +

SYNOPSIS

+
+#include<mach/etap.h>
+
+kern_return_t   etap_trace_thread
+                (thread_act_t                     target_thread,
+                 boolean_t                               active);
+
+

PARAMETERS

+
+

+

target_thread +
+The port of the thread who's ETAP trace status will be toggled. +

+

active +
+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. +
+

DESCRIPTION

+

+The etap_trace_thread system call is used to +toggle the ETAP trace status of a thread. +

RETURN VALUES

+
+
KERN_SUCCESS +
+ The call was performed successfully. +

+

KERN_INVALID_ARGUMENT +
+ The value of target_thread does not name a valid thread. +

+

KERN_FAILURE +
+ ETAP is not configured in the kernel. +
+

RELATED INFORMATION

+

+Functions: +etap_probe, +etap_trace_event, +etap_get_info. 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 @@ -

evc_wait

System Trap - Wait for a kernel (device) signalled event.

SYNOPSIS

kern_return_t	evc_wait
		(unsigned int	event);

PARAMETERS

event
[in scalar] The task local event ID of the kernel event object.

DESCRIPTION

The evc_wait function causes the invoking thread to wait until the specified kernel (device) generated event occurs. Device drivers (typically mapped devices intended to be supported by user space drivers) may supply an event service. The event service defines one or more event objects, named by task local event IDs. Each of these event objects has an associated event count, initially zero. Whenever the associated event occurs (typically a device interrupt), the event count is incremented. If this count is zero when evc_wait is called, the calling thread waits for the next event to occur. Only one thread may be waiting for the event to occur. If the count is non-zero when evc_wait is called, the count is simply decremented without causing the thread to wait. The event count guarantees that no events are lost.

NOTES

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 device_map) and signal the associated event. The user space device driver would normally be waiting with evc_wait. 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.

RETURN VALUES

KERN_NO_SPACE
There is already a thread waiting for this event.

RELATED INFORMATION

Functions: device_map. \ No newline at end of file +

evc_wait

+
+

+System Trap - Wait for a kernel (device) signalled event. +

SYNOPSIS

+
+kern_return_t	evc_wait
+		(unsigned int	event);
+
+

PARAMETERS

+
+
event +
+[in scalar] The task local event ID of the kernel event object. +
+

DESCRIPTION

+

+The evc_wait function causes the invoking thread to wait until the +specified kernel (device) generated event occurs. Device drivers +(typically mapped devices intended to be supported by user space +drivers) may supply an event service. The event service defines one +or more event objects, named by task local event IDs. Each of these +event objects has an associated event count, initially zero. Whenever +the associated event occurs (typically a device interrupt), the event +count is incremented. If this count is zero when evc_wait is called, +the calling thread waits for the next event to occur. Only one thread +may be waiting for the event to occur. If the count is non-zero when +evc_wait is called, the count is simply decremented without causing +the thread to wait. The event count guarantees that no events are +lost. +

NOTES

+

+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 device_map) and +signal the associated event. The user space device driver would +normally be waiting with evc_wait. 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. +

RETURN VALUES

+
+
KERN_NO_SPACE +
+There is already a thread waiting for this event. +
+

RELATED INFORMATION

+

+Functions: +device_map. 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 @@ -

exc_server

Function - Handle kernel-reported thread exception.

SYNOPSIS

boolean_t	exc_server
		(mach_msg_header_t	request_msg,
		mach_msg_header_t	reply_ms);

PARAMETERS

in_msg
[pointer to in structure] The exception message received from the kernel.

out_msg
[out structure] A reply message.

DESCRIPTION

The exc_server 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 thread_set_exception_ports or task_set_exception_ports. 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 exc_server function performs all necessary argument handling for this kernel message and calls catch_exception_raise, catch_exception_raise_state or catch_exception_raise_state_identity, which should handle the exception. If the called routine returns KERN_SUCCESS, 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.

RETURN VALUES

TRUE
The message was handled and the appropriate function was called.

FALSE
The message did not apply to the exception mechanism and no other action was taken.

RELATED INFORMATION

Functions: catch_exception_raise. \ No newline at end of file +

exc_server

+
+

+Function - Handle kernel-reported thread exception. +

SYNOPSIS

+
+boolean_t	exc_server
+		(mach_msg_header_t	request_msg,
+		mach_msg_header_t	reply_ms);
+
+

PARAMETERS

+
+

+

in_msg +
+[pointer to in structure] +The exception message received from the +kernel. +

+

out_msg +
+[out structure] +A reply message. +
+

DESCRIPTION

+

+The exc_server 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 +thread_set_exception_ports or task_set_exception_ports. +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 exc_server +function performs +all necessary argument handling for this kernel message and calls +catch_exception_raise, catch_exception_raise_state or +catch_exception_raise_state_identity, which should handle the +exception. If the called routine +returns KERN_SUCCESS, 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. +

RETURN VALUES

+
+

+

TRUE +
+The message was handled and the appropriate function was called. +

+

FALSE +
+The message did not apply to the exception mechanism and no other +action was taken. +
+

RELATED INFORMATION

+

+Functions: +catch_exception_raise. 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 @@ -

host_adjust_time

Function - Gradually change the time.

SYNOPSIS

#include< mach/mach_host.h>

kern_return_t   host_adjust_time
                (host_priv_t                          host_priv,
                 time_value_t                    new_adjustment,
                 time_value_t                    old_adjustment);

PARAMETERS

host_priv
[in host-control port] The control port the host for which the time is to be set.

new_adjustment
[in structure] New adjustment value.

old_adjustment
[out structure] Old adjustment value.

DESCRIPTION

The host_adjust_time function arranges for the time on a specified host to be gradually changed by an adjustment value.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_get_time, host_set_time.

Data Structures: time_value. \ No newline at end of file +

host_adjust_time

+
+

+Function - Gradually change the time. +

SYNOPSIS

+
+#include< mach/mach_host.h>
+
+kern_return_t   host_adjust_time
+                (host_priv_t                          host_priv,
+                 time_value_t                    new_adjustment,
+                 time_value_t                    old_adjustment);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control port] The control port the host for which the time is to be set. +

+

new_adjustment +
+[in structure] New adjustment value. +

+

old_adjustment +
+[out structure] Old adjustment value. +
+

DESCRIPTION

+

+The host_adjust_time function arranges for the time on a specified host to be gradually changed by an adjustment value. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_get_time, +host_set_time. +

+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 @@ -

host_basic_info

Structure - Used to present basic information about a host.

SYNOPSIS

struct host_basic_info
{
       integer_t            max_cpus;
       integer_t            avail_cpus;
       vm_size_t            memory_size;
       cpu_type_t           cpu_type;
       cpu_subtype_t        cpu_subtype;
       cpu_threadtype_t     cpu_threadtype;
       integer_t            physical_cpu;
       integer_t            physical_cpu_max;
       integer_t            logical_cpu;
       integer_t            logical_cpu_max;
       uint64_t             max_mem;
};

typedef struct host_basic_info* host_basic_info_t;

FIELDS

max_cpus
Maximum number of CPUs possible

avail_cpus
Number of CPUs now available

memory_size
Size of memory in bytes, capped at 2 GB

cpu_type
CPU type

cpu_subtype
CPU sub-type

cpu_threadtype
CPU thread-type

physical_cpu
Number of physical CPUs now available

physical_cpu_max
Maximum number of physical CPUs possible

logical_cpu
Number of logical CPUs now available

logical_cpu_max
Maximum number of logical CPUs possible

max_mem
Actual size of physical memory in bytes

DESCRIPTION

The host_basic_info structure defines the basic information available about a host.

NOTES

This structure is machine word length specific because of the memory size returned.

RELATED INFORMATION

Functions: host_info.

Data Structures: host_load_info, host_sched_info. \ No newline at end of file +

host_basic_info

+
+

+Structure - Used to present basic information about a host. +

SYNOPSIS

+
+struct host_basic_info
+{
+       integer_t            max_cpus;
+       integer_t            avail_cpus;
+       vm_size_t            memory_size;
+       cpu_type_t           cpu_type;
+       cpu_subtype_t        cpu_subtype;
+       cpu_threadtype_t     cpu_threadtype;
+       integer_t            physical_cpu;
+       integer_t            physical_cpu_max;
+       integer_t            logical_cpu;
+       integer_t            logical_cpu_max;
+       uint64_t             max_mem;
+};
+
+typedef struct host_basic_info* host_basic_info_t;
+
+

FIELDS

+
+
max_cpus +
+Maximum number of CPUs possible +

+

avail_cpus +
+Number of CPUs now available +

+

memory_size +
+Size of memory in bytes, capped at 2 GB +

+

cpu_type +
+CPU type +

+

cpu_subtype +
+CPU sub-type +

+

cpu_threadtype +
+CPU thread-type +

+

physical_cpu +
+Number of physical CPUs now available +

+

physical_cpu_max +
+Maximum number of physical CPUs possible +

+

logical_cpu +
+Number of logical CPUs now available +

+

logical_cpu_max +
+Maximum number of logical CPUs possible +

+

max_mem +
+Actual size of physical memory in bytes +
+

DESCRIPTION

+

+The host_basic_info structure defines the basic information +available about a +host. +

NOTES

+

+This structure is machine word length specific because of the memory size +returned. +

RELATED INFORMATION

+

+Functions: +host_info. +

+Data Structures: +host_load_info, +host_sched_info. 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 @@ -

host_get_boot_info

Function - Return operator boot information.

SYNOPSIS

kern_return_t   host_get_boot_info
                (host_priv_t                          priv_host,
                 kernel_boot_info_t                   boot_info);

PARAMETERS

priv_host
[in host-control send right] The control port for the host for which information is to be obtained.

boot_info
[out array of char] Character string providing the operator boot info

DESCRIPTION

The host_get_boot_info function returns the boot-time information string supplied by the operator when priv_host was initialized. The constant KERNEL_BOOT_INFO_MAX (in \*L\*O) should be used to dimension storage for the returned string.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_info. \ No newline at end of file +

host_get_boot_info

+
+

+Function - Return operator boot information. +

SYNOPSIS

+
+kern_return_t   host_get_boot_info
+                (host_priv_t                          priv_host,
+                 kernel_boot_info_t                   boot_info);
+
+

PARAMETERS

+
+

+

priv_host +
+[in host-control send right] +The control port for the host for which +information is to be obtained. +

+

boot_info +
+[out array of char] +Character string providing the operator boot info +
+

DESCRIPTION

+

+The host_get_boot_info function returns the boot-time information +string supplied by the operator when priv_host was initialized. +The constant KERNEL_BOOT_INFO_MAX (in \*L\*O) +should be used to dimension storage for the returned string. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_info. 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 @@ -

host_get_clock_control

Function - Return a send right to a kernel clock's control port.

SYNOPSIS

kern_return_t   host_get_clock_control
                (host_priv_t                          host_priv,
                 clock_id_t                                  id,
                 clock_ctrl_t                     clock_control);

PARAMETERS

host_priv
[in host-control send right] The control port for the host owning the clock.

id
[in scalar] The identification of the desired kernel clock. These values are defined in \*L\*O. Although an implementation may define additional values, the following values are always defined (although only the REALTIME clock is required to be implemented):

REALTIME_CLOCK
A moderate resolution clock service that (typically) tracks time since the system last boot.

BATTERY_CLOCK
A (typically) low resolution clock (to the second) that survives power failures or service outages.

HIGHRES_CLOCK
A high resolution clock.

clock_control
[out clock-control send right] Control port for the clock.

DESCRIPTION

The host_get_clock_control 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: clock_set_time, clock_set_attributes, host_get_clock_service. \ No newline at end of file +

host_get_clock_control

+
+

+Function - Return a send right to a kernel clock's control port. +

SYNOPSIS

+
+kern_return_t   host_get_clock_control
+                (host_priv_t                          host_priv,
+                 clock_id_t                                  id,
+                 clock_ctrl_t                     clock_control);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control send right] +The control port for the host owning the +clock. +

+

id +
+[in scalar] +The identification of the desired kernel clock. These values +are defined in \*L\*O. Although an implementation +may define additional values, the following values are always defined +(although only the REALTIME clock is required to be implemented): +
+

+

REALTIME_CLOCK +
+A moderate resolution clock service that (typically) tracks +time since the system last boot. +

+

BATTERY_CLOCK +
+A (typically) low resolution clock (to the second) that +survives power failures or service outages. +

+

HIGHRES_CLOCK +
+A high resolution clock. +
+

+

clock_control +
+[out clock-control send right] +Control port for the clock. +
+

DESCRIPTION

+

+The host_get_clock_control 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +clock_set_time, +clock_set_attributes, +host_get_clock_service. 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 @@ -

host_get_clock_service

Function - Return a send right to a kernel clock's service port.

SYNOPSIS

kern_return_t   host_get_clock_service
                (host_t                                    host,
                 clock_id_t                                  id,
                 clock_t                             clock_name);

PARAMETERS

host
[in host-name send right] The name (or control) port for the host owning the clock.

id
[in scalar] The identification of the desired kernel clock. These values are defined in \*L\*O. Although an implementation may define additional values, the following values are always defined (although only the REALTIME clock is required to be implemented):

REALTIME_CLOCK
A moderate resolution clock service that (typically) tracks time since the system last boot.

BATTERY_CLOCK
A (typically) low resolution clock (to the second) that survives power failures or service outages.

HIGHRES_CLOCK
A high resolution clock.

clock_name
[out clock-name send right] Name port for the clock.

DESCRIPTION

The host_get_clock_service 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: clock_get_time, clock_get_attributes, clock_map_time, clock_sleep, clock_alarm, host_get_clock_control. \ No newline at end of file +

host_get_clock_service

+
+

+Function - Return a send right to a kernel clock's service port. +

SYNOPSIS

+
+kern_return_t   host_get_clock_service
+                (host_t                                    host,
+                 clock_id_t                                  id,
+                 clock_t                             clock_name);
+
+

PARAMETERS

+
+

+

host +
+[in host-name send right] +The name (or control) port for the host +owning the clock. +

+

id +
+[in scalar] +The identification of the desired kernel clock. These values +are defined in \*L\*O. Although an implementation +may define additional values, the following values are always defined +(although only the REALTIME clock is required to be implemented): +
+

+

REALTIME_CLOCK +
+A moderate resolution clock service that (typically) tracks +time since the system last boot. +

+

BATTERY_CLOCK +
+A (typically) low resolution clock (to the second) that +survives power failures or service outages. +

+

HIGHRES_CLOCK +
+A high resolution clock. +
+

+

clock_name +
+[out clock-name send right] +Name port for the clock. +
+

DESCRIPTION

+

+The host_get_clock_service 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +clock_get_time, +clock_get_attributes, +clock_map_time, +clock_sleep, +clock_alarm, +host_get_clock_control. 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 @@ -

host_get_time

Function - Return the current time.

SYNOPSIS

#include< mach/mach_host.h>

kern_return_t   host_get_time
                (host_t                                    host,
                 time_value_t                      current_time);

PARAMETERS

host
[in host-name port] The name port the host for which the time is to be set.

current_time
[out structure] Returned time value.

DESCRIPTION

The host_get_time function returns the current time as seen by that host.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_adjust_time, host_set_time.

Data Structures: time_value. \ No newline at end of file +

host_get_time

+
+

+Function - Return the current time. +

SYNOPSIS

+
+#include< mach/mach_host.h>
+
+kern_return_t   host_get_time
+                (host_t                                    host,
+                 time_value_t                      current_time);
+
+

PARAMETERS

+
+

+

host +
+[in host-name port] The name port the host for which the time is to be set. +

+

current_time +
+[out structure] Returned time value. +
+

DESCRIPTION

+

+The host_get_time function returns the current time +as seen by that host. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_adjust_time, +host_set_time. +

+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 @@ -

host_info

Function - Return information about a host.

SYNOPSIS

kern_return_t   host_info
                (host_t                                    host,
                 host_flavor_t                           flavor,
                 host_info_t                          host_info,
                 mach_msg_type_number_t         host_info_count);

PARAMETERS

host
[in host-name send right] The name (or control) port for the host for which information is to be obtained.

flavor
[in scalar] The type of statistics desired:

HOST_BASIC_INFO
Basic information (number of processors, amount of memory). The returned structure is host_basic_info.

HOST_SCHED_INFO
Basic restrictions of the kernel's scheduling, minimum quantum and time-out value. The returned structure is host_sched_info.

HOST_RESOURCE_SIZES
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 kernel_resource_sizes.

host_info
[out structure] Statistics about the specified host.

host_info_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The host_info function returns selected information about a host, as specified by flavor.

NOTES

This interface is machine word length specific because of the memory size returned by HOST_BASIC_INFO.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_get_boot_info, host_kernel_version, host_statistics.

Data Structures: host_basic_info, host_sched_info, kernel_resource_sizes. \ No newline at end of file +

host_info

+
+

+Function - Return information about a host. +

SYNOPSIS

+
+kern_return_t   host_info
+                (host_t                                    host,
+                 host_flavor_t                           flavor,
+                 host_info_t                          host_info,
+                 mach_msg_type_number_t         host_info_count);
+
+

PARAMETERS

+
+

+

host +
+[in host-name send right] +The name (or control) port for the host for +which information is to be obtained. +

+

flavor +
+[in scalar] +The type of statistics desired: +
+

+

HOST_BASIC_INFO +
+Basic information (number of processors, amount of +memory). The returned structure is host_basic_info. +

+

HOST_SCHED_INFO +
+Basic restrictions of the kernel's scheduling, minimum +quantum and time-out value. The returned structure is +host_sched_info. +

+

HOST_RESOURCE_SIZES +
+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 kernel_resource_sizes. +
+

+

host_info +
+[out structure] +Statistics about the specified host. +

+

host_info_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The host_info function returns selected information +about a host, as specified +by flavor. +

NOTES

+

+This interface is machine word length specific because of the memory size +returned by HOST_BASIC_INFO. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_get_boot_info, +host_kernel_version, +host_statistics. +

+Data Structures: +host_basic_info, +host_sched_info, +kernel_resource_sizes. 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 @@ -

host_kernel_version

Function - Return kernel version information for a host.

SYNOPSIS

kern_return_t   host_kernel_version
                (host_t                                    host,
                 kernel_version_t                       version);

PARAMETERS

host
[in host-name send right] The name (or control) port for the host for which information is to be obtained.

version
[out array of char] Character string describing the kernel version executing on host.

DESCRIPTION

The host_kernel_version function returns the version string compiled into the kernel executing on host at the time it was built. This describes the version of the kernel. The constant KERNEL_VERSION_MAX (in \*L\*O) should be used to dimension storage for the returned string if the kernel_version_t declaration is not used.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_info. \ No newline at end of file +

host_kernel_version

+
+

+Function - Return kernel version information for a host. +

SYNOPSIS

+
+kern_return_t   host_kernel_version
+                (host_t                                    host,
+                 kernel_version_t                       version);
+
+

PARAMETERS

+
+

+

host +
+[in host-name send right] +The name (or control) port for the host for +which information is to be obtained. +

+

version +
+[out array of char] +Character string describing the kernel version +executing on host. +
+

DESCRIPTION

+

+The host_kernel_version function returns the version +string compiled into the +kernel executing on host at the time it was built. This describes +the version of the kernel. The constant KERNEL_VERSION_MAX (in +\*L\*O) +should be used to dimension storage for the returned string if the +kernel_version_t declaration is not used. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_info. 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 @@ -

host_load_info

Structure - Used to present a host's processor load information.

SYNOPSIS

#define CPU_STATE_USER     0

#define CPU_STATE_SYSTEM   1

#define CPU_STATE_IDLE     2

struct host_load_info
{
       integer_t        avenrun[3];
       integer_t    mach_factor[3];
};

typedef struct host_load_info* host_load_info_t;

FIELDS

avenrun
load average--average number of runnable processes divided by number of CPUs

mach_factor
The processing resources available to a new thread--the number of CPUs divided by (1 + the number of threads)

DESCRIPTION

The host_load_info 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.

RELATED INFORMATION

Functions: host_statistics.

Data Structures: host_basic_info, host_sched_info. \ No newline at end of file +

host_load_info

+
+

+Structure - Used to present a host's processor load information. +

SYNOPSIS

+
+#define CPU_STATE_USER     0
+
+#define CPU_STATE_SYSTEM   1
+
+#define CPU_STATE_IDLE     2
+
+struct host_load_info
+{
+       integer_t        avenrun[3];
+       integer_t    mach_factor[3];
+};
+
+typedef struct host_load_info* host_load_info_t;
+
+

FIELDS

+
+
avenrun +
+load average--average number of runnable processes divided by +number of CPUs +

+

mach_factor +
+The processing resources available to a new thread--the number of +CPUs divided by (1 + the number of threads) +
+

DESCRIPTION

+

+The host_load_info 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. +

RELATED INFORMATION

+

+Functions: +host_statistics. +

+Data Structures: +host_basic_info, +host_sched_info. + 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 @@ -

host_page_size

Function - Provide the system's virtual page size.

SYNOPSIS

kern_return_t   host_page_size
                (host_t                                    host,
                 vm_size_t                            page_size);

PARAMETERS

host
[in host-name send right] The name (or control) port for the host for which the page size is desired.

page_size
[out scalar] The host's page size (in bytes).

DESCRIPTION

The host_page_size function returns the page size for the given host.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_host_self. \ No newline at end of file +

host_page_size

+
+

+Function - Provide the system's virtual page size. +

SYNOPSIS

+
+kern_return_t   host_page_size
+                (host_t                                    host,
+                 vm_size_t                            page_size);
+
+

PARAMETERS

+
+

+

host +
+[in host-name send right] +The name (or control) port for the host for +which the page size is desired. +

+

page_size +
+[out scalar] +The host's page size (in bytes). +
+

DESCRIPTION

+

+The host_page_size function returns the page size for the given host. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_host_self. 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 @@ -

host_processor_set_priv

Function - Translate a processor set name port into a processor set control port.

SYNOPSIS

kern_return_t   host_processor_set_priv
                (host_priv_t                          host_priv,
                 processor_set_name_t                  set_name,
                 processor_set_t                  processor_set);

PARAMETERS

host_priv
[in host-control send right] The control port for the host for which the processor set is desired.

set_name
[in processor-set-name send right] The name port for the processor set desired.

processor_set
[out processor-set-control send right] The returned processor set control port.

DESCRIPTION

The host_processor_set_priv function returns send rights for the control port for a specified processor set currently existing on host_priv.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_processor_sets, processor_set_create, processor_set_tasks, processor_set_threads. \ No newline at end of file +

host_processor_set_priv

+
+

+Function - Translate a processor set name port + into a processor set control port. +

SYNOPSIS

+
+kern_return_t   host_processor_set_priv
+                (host_priv_t                          host_priv,
+                 processor_set_name_t                  set_name,
+                 processor_set_t                  processor_set);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control send right] +The control port for the host for which the +processor set is desired. +

+

set_name +
+[in processor-set-name send right] +The name port for the processor set +desired. +

+

processor_set +
+[out processor-set-control send right] +The returned processor set +control port. +
+

DESCRIPTION

+

+The host_processor_set_priv function returns send rights +for the control port +for a specified processor set currently existing on host_priv. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_processor_sets, +processor_set_create, +processor_set_tasks, +processor_set_threads. 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 @@ -

host_processor_sets

Function - Return a list of send rights representing all processor set name ports.

SYNOPSIS

kern_return_t   host_processor_sets
                (host_priv_t                          host_priv,
                 processor_set_name_port_array_tprocessor_set_name_list,
                 host_priv             processor_set_name_count);

PARAMETERS

host_priv
[in host-control send right] The control port for the host for which the processor sets are desired.

processor_set_name_list
[out pointer to dynamic array of processor-set-name send rights] The set of processor set name ports for those currently existing on host_priv; no particular order is guaranteed.

processor_set_name_count
[out scalar] The number of processor set names returned.

DESCRIPTION

The host_processor_sets function returns send rights for the name ports for each processor set currently existing on host.

NOTES

If control ports to the processor sets are needed, use host_processor_set_priv.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_processor_set_priv, processor_set_create, processor_set_tasks, processor_set_threads. \ No newline at end of file +

host_processor_sets

+
+

+Function - Return a list of send rights representing all processor set name ports. + +

SYNOPSIS

+
+kern_return_t   host_processor_sets
+                (host_priv_t                          host_priv,
+                 processor_set_name_port_array_tprocessor_set_name_list,
+                 host_priv             processor_set_name_count);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control send right] +The control port for the host for which the +processor sets are desired. +

+

processor_set_name_list +
+[out pointer to dynamic array of processor-set-name send rights] +The +set of processor set name ports for those currently existing on +host_priv; no particular order is guaranteed. +

+

processor_set_name_count +
+[out scalar] +The number of processor set names returned. +
+

DESCRIPTION

+

+The host_processor_sets function returns send rights +for the name ports for +each processor set currently existing on host. +

NOTES

+

+If control ports to the processor sets are needed, use +host_processor_set_priv. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_processor_set_priv, +processor_set_create, +processor_set_tasks, +processor_set_threads. 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 @@ -

host_processor_slots

Function - Return a list of numbers that map processor slots to active processors.

SYNOPSIS

kern_return_t   host_processor_slots
                (host_t                                    host,
                 processor_slot_t                         slots,
                 host                                     count);

PARAMETERS

host
[in host-name send right] The name (or control) port for the host for which information is to be obtained.

slots
[out array of processor_slot_t] An array of the processor slot numbers for active processors.

count
[pointer to in/out scalar] On input, the maximum size of the slots buffer; on output, the number of returned slot numbers.

DESCRIPTION

The host_processor_slots function returns an array of the processor slots defined for the host.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_info, host_processors, processor_info. \ No newline at end of file +

host_processor_slots

+
+

+Function - Return a list of numbers that map processor slots to active processors. +

SYNOPSIS

+
+kern_return_t   host_processor_slots
+                (host_t                                    host,
+                 processor_slot_t                         slots,
+                 host                                     count);
+
+

PARAMETERS

+
+

+

host +
+[in host-name send right] +The name (or control) port for the host for +which information is to be obtained. +

+

slots +
+[out array of processor_slot_t] +An array of the processor slot numbers +for active processors. +

+

count +
+[pointer to in/out scalar] +On input, the maximum size of the slots +buffer; on output, the number of returned slot numbers. +
+

DESCRIPTION

+

+The host_processor_slots function returns an array +of the processor slots +defined for the host. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_info, +host_processors, +processor_info. 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 @@ -

host_processors

Function - Return a list of send rights representing all processor ports.

SYNOPSIS

kern_return_t   host_processors
                (host_t                               host_priv,
                 processor_port_array_t          processor_list,
                 host_priv                      processor_count);

PARAMETERS

host_priv
[in host-control send right] The control port for the desired host.

processor_list
[out pointer to dynamic array of processor send rights] The set of processors existing on host_priv; no particular order is guaranteed.

processor_count
[out scalar] The number of ports returned in processor_list.

DESCRIPTION

The host_processors function returns an array of send right ports for each processor existing on host_priv.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_start, processor_exit, processor_info, processor_control, host_processor_slots. \ No newline at end of file +

host_processors

+
+

+Function - Return a list of send rights representing all processor ports. +

SYNOPSIS

+
+kern_return_t   host_processors
+                (host_t                               host_priv,
+                 processor_port_array_t          processor_list,
+                 host_priv                      processor_count);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control send right] +The control port for the desired host. +

+

processor_list +
+[out pointer to dynamic array of processor send rights] +The set of +processors existing on host_priv; no particular order is guaranteed. +

+

processor_count +
+[out scalar] +The number of ports returned in processor_list. +
+

DESCRIPTION

+

+The host_processors function returns an array of send +right ports for each +processor existing on host_priv. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_start, +processor_exit, +processor_info, +processor_control, +host_processor_slots. 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 @@ -

host_reboot

Function - Reboot this host.

SYNOPSIS

kern_return_t   host_reboot
                (host_priv_t                          host_priv,
                 int                                    options);

PARAMETERS

host_priv
[in host-control send right] The control port the host to be re-booted.

options
[in scalar] Reboot options. See \*L\*O for details.

DESCRIPTION

The host_reboot function reboots the specified host.

NOTES

If successful, this call will not return.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

None. \ No newline at end of file +

host_reboot

+
+

+Function - Reboot this host. +

SYNOPSIS

+
+kern_return_t   host_reboot
+                (host_priv_t                          host_priv,
+                 int                                    options);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control send right] +The control port the host to be re-booted. +

+

options +
+[in scalar] +Reboot options. See \*L\*O for details. +
+

DESCRIPTION

+

+The host_reboot function reboots the specified host. +

NOTES

+

+If successful, this call will not return. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+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 @@ -

host_sched_info

Structure - Used to present the set of scheduler limits associated with the host.

SYNOPSIS

struct host_sched_info
{
       integer_t       min_timeout;
       integer_t       min_quantum;
};

typedef struct host_sched_info* host_sched_info_t;

FIELDS

min_timeout
Minimum time-out, in milliseconds

min_quantum
Minimum quantum (period for which a thread can be scheduled if uninterrupted), in milliseconds

DESCRIPTION

The host_sched_info structure defines the limiting scheduling information available about a host.

RELATED INFORMATION

Functions: host_info.

Data Structures: host_basic_info, host_load_info. \ No newline at end of file +

host_sched_info

+
+

+Structure - Used to present the set of scheduler limits associated + with the host. +

SYNOPSIS

+
+struct host_sched_info
+{
+       integer_t       min_timeout;
+       integer_t       min_quantum;
+};
+
+typedef struct host_sched_info* host_sched_info_t;
+
+

FIELDS

+
+
min_timeout +
+Minimum time-out, in milliseconds +

+

min_quantum +
+Minimum quantum (period for which a thread can be scheduled if +uninterrupted), in milliseconds +
+

DESCRIPTION

+

+The host_sched_info structure defines the limiting +scheduling information +available about a host. +

RELATED INFORMATION

+

+Functions: +host_info. +

+Data Structures: +host_basic_info, +host_load_info. 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 @@ -

host_security_create_task_token

Function - Create a new task with an explicit security token.

SYNOPSIS

kern_return_t   host_security_create_task_token
                (host_security_t                  host_security,
                 task_t                             parent_task,
                 security_token_t                security_token,
                 audit_token_t                      audit_token,
                 ledger_port_array_t                    ledgers,
                 boolean_t                       inherit_memory,
                 task_t                             child_task);

PARAMETERS

host_security
[in security send right] The host's security port.

parent_task
[in task send right] The port for the task from which to draw the child task's port rights and address space.

security_token
[in scalar] The task's security token.

audit_token
[in scalar] The task's audit token.

ledgers
[pointer to in array of ledger send rights] The set of ledgers from which the task will draw its resources.

inherit_memory
[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.

child_task
[out task send right] The kernel-assigned port name for the new task.

DESCRIPTION

The host_security_create_task_token function creates a new task from parent_task with explicit security and audit token values, returning the name of the new task in the parameter specified by child_task. Other than the security and audit token values, the child task is as if created by task_create.

NOTES

The host security port is a privileged port given to the system bootstrap task for the use of this call.

RETURN VALUES

KERN_INVALID_SECURITY
The value of host_security does not specify the security port for the host on which task lies.

RELATED INFORMATION

Functions: task_create, host_security_set_task_token, mach_msg. \ No newline at end of file +

host_security_create_task_token

+
+

+Function - Create a new task with an explicit security token. +

SYNOPSIS

+
+kern_return_t   host_security_create_task_token
+                (host_security_t                  host_security,
+                 task_t                             parent_task,
+                 security_token_t                security_token,
+                 audit_token_t                      audit_token,
+                 ledger_port_array_t                    ledgers,
+                 boolean_t                       inherit_memory,
+                 task_t                             child_task);
+
+

PARAMETERS

+
+

+

host_security +
+[in security send right] The host's security port. +

+

parent_task +
+[in task send right] The port for the task from which to draw the child +task's port rights and address space. +

+

security_token +
+[in scalar] The task's security token. +

+

audit_token +
+[in scalar] The task's audit token. +

+

ledgers +
+[pointer to in array of ledger send rights] The set of ledgers from which the +task will draw its resources. +

+

inherit_memory +
+[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. +

+

child_task +
+[out task send right] The kernel-assigned port name for the new task. +
+

DESCRIPTION

+

+The host_security_create_task_token function creates a new task from +parent_task with explicit security and audit token values, returning the name of the +new task in the parameter specified by child_task. Other than the security and audit token values, the child task +is as if created by task_create. +

NOTES

+

+The host security port is a privileged port given to the system +bootstrap task for the use of this call. +

RETURN VALUES

+
+

+

KERN_INVALID_SECURITY +
+The value of host_security does not specify the security port for the host on which task lies. +
+

RELATED INFORMATION

+

+Functions: +task_create, +host_security_set_task_token, +mach_msg. 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 @@ -

host_security_set_task_token

Function - Change the target task's security token.

SYNOPSIS

kern_return_t   host_security_set_task_token
                (host_security_t                  host_security,
                 task_t                                    task,
                 security_token_t                security_token,
                 audit_token_t                      audit_token,
                 host_t                                    host);

PARAMETERS

host_security
[in security send right] The host's security port.

task
[in task send right] The port for the task for which the token is to be set.

security_token
[in scalar] The new security token.

audit_token
[in scalar] The new audit token.

host
[in host send right] The task's new host-self port.

DESCRIPTION

The host_security_set_task_token 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.

NOTES

The host security port is a privileged port given to the system bootstrap task for the use of this call.

RETURN VALUES

KERN_INVALID_SECURITY
The value of host_security does not specify the security port for the host on which task lies.

RELATED INFORMATION

Functions: task_create, task_info, mach_msg. \ No newline at end of file +

host_security_set_task_token

+
+

+Function - Change the target task's security token. +

SYNOPSIS

+
+kern_return_t   host_security_set_task_token
+                (host_security_t                  host_security,
+                 task_t                                    task,
+                 security_token_t                security_token,
+                 audit_token_t                      audit_token,
+                 host_t                                    host);
+
+

PARAMETERS

+
+

+

host_security +
+[in security send right] The host's security port. +

+

task +
+[in task send right] The port for the task for which the token is to be set. +

+

security_token +
+[in scalar] The new security token. +

+

audit_token +
+[in scalar] The new audit token. +

+

host +
+[in host send right] The task's new host-self port. +
+

DESCRIPTION

+

+The host_security_set_task_token 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. +

NOTES

+

+The host security port is a privileged port given to the system +bootstrap task for the use of this call. +

RETURN VALUES

+
+

+

KERN_INVALID_SECURITY +
+The value of host_security does not specify the security port for the host on which task lies. +
+

RELATED INFORMATION

+

+Functions: +task_create, +task_info, +mach_msg. 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 @@ -

host_set_time

Function - Sets the time.

SYNOPSIS

#include< mach/mach_host.h>

kern_return_t   host_set_time
                (host_priv_t                          host_priv,
                 time_value_t                          new_time);

PARAMETERS

host_priv
[in host-control port] The control port for the host for which the time is to be set.

new_time
[in structure] Time to be set.

DESCRIPTION

The host_set_time function establishes the time on the specified host.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_adjust_time, host_get_time.

Data Structures: time_value. \ No newline at end of file +

host_set_time

+
+

+Function - Sets the time. +

SYNOPSIS

+
+#include< mach/mach_host.h>
+
+kern_return_t   host_set_time
+                (host_priv_t                          host_priv,
+                 time_value_t                          new_time);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control port] The control port for the host for which the time is to be set. +

+

new_time +
+[in structure] Time to be set. +
+

DESCRIPTION

+

+The host_set_time function establishes the time on the specified host. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_adjust_time, +host_get_time. +

+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 @@ -

host_statistics

Function - Return statistics for a host.

SYNOPSIS

kern_return_t   host_statistics
                (host_priv_t                          host_priv,
                 host_flavor_t                           flavor,
                 host_info_t                          host_info,
                 mach_msg_type_number_t         host_info_count);

PARAMETERS

host_priv
[in host-control send right] The control port for the host for which information is to be obtained.

flavor
[in scalar] The type of statistics desired.

HOST_LOAD_INFO
System loading statistics. The returned structure is host_load_info.

HOST_VM_INFO
Virtual memory statistics. The returned structure is vm_statistics.

host_info
[out structure] Statistics about the specified host.

host_info_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The host_statistics function returns scheduling and virtual memory statistics concerning the host as specified by flavor.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: host_info, processor_set_statistics.

Data Structures: host_load_info, vm_statistics. \ No newline at end of file +

host_statistics

+
+

+Function - Return statistics for a host.

SYNOPSIS

+
+kern_return_t   host_statistics
+                (host_priv_t                          host_priv,
+                 host_flavor_t                           flavor,
+                 host_info_t                          host_info,
+                 mach_msg_type_number_t         host_info_count);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control send right] +The control port for the host for which +information is to be obtained. +

+

flavor +
+[in scalar] +The type of statistics desired. +
+

+

HOST_LOAD_INFO +
+System loading statistics. The returned structure is +host_load_info. +

+

HOST_VM_INFO +
+Virtual memory statistics. The returned structure is +vm_statistics. +
+

+

host_info +
+[out structure] +Statistics about the specified host. +

+

host_info_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The host_statistics function returns scheduling and +virtual memory statistics +concerning the host as specified by flavor. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +host_info, +processor_set_statistics. +

+Data Structures: +host_load_info, +vm_statistics. 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 @@ -

i386_get_ldt

Function - Return per-thread segment descriptors.

SYNOPSIS

kern_return_t   i386_get_ldt
                (thread_act_t                        target_act,
                 int                             first_selector,
                 int                              desired_count,
                 descriptor_list_t                    desc_list);

PARAMETERS

target_act
[in thread send right] Thread whose segment descriptors are to be returned.

first_selector
[in scalar] Selector value (segment register value) corresponding to the first segment whose descriptor is to be returned.

desired_count
[in scalar] Number of returned descriptors desired.

desc_list
[out pointer to dynamic array of descriptor_t] Array of segment descriptors.

DESCRIPTION

The i386_get_ldt function returns per-thread segment descriptors from the thread's local descriptor table (LDT).

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: i386_set_ldt. \ No newline at end of file +

i386_get_ldt

+
+

+Function - Return per-thread segment descriptors. +

SYNOPSIS

+
+kern_return_t   i386_get_ldt
+                (thread_act_t                        target_act,
+                 int                             first_selector,
+                 int                              desired_count,
+                 descriptor_list_t                    desc_list);
+
+

PARAMETERS

+
+

+

target_act +
+[in thread send right] +Thread whose segment descriptors are to be +returned. +

+

first_selector +
+[in scalar] Selector value (segment register value) corresponding to the +first segment whose descriptor is to be returned. +

+

desired_count +
+[in scalar] +Number of returned descriptors desired. +

+

desc_list +
+[out pointer to dynamic array of descriptor_t] +Array of segment +descriptors. +
+

DESCRIPTION

+

+The i386_get_ldt function returns per-thread segment +descriptors from the +thread's local descriptor table (LDT). +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +i386_set_ldt. 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 @@ -

i386_io_port_add

Function - Permit target thread to invoke operations on the specified device.

SYNOPSIS

kern_return_t   i386_io_port_add
                (thread_act_t                        target_act,
                 device_t                                device);

PARAMETERS

target_act
[in thread send right] Thread whose permission bitmap is to be set.

device
[in device send right] The device to which I/O instructions are to be permitted.

DESCRIPTION

The i386_io_port_add 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.

NOTES

Normally, the thread must have called i386_io_port_add for all devices to which it will execute I/O instructions. However, possessing send rights to the iopl device port will cause the iopl 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: i386_io_port_list, i386_io_port_remove. \ No newline at end of file +

i386_io_port_add

+
+

+Function - Permit target thread to invoke operations on the specified device. +

SYNOPSIS

+
+kern_return_t   i386_io_port_add
+                (thread_act_t                        target_act,
+                 device_t                                device);
+
+

PARAMETERS

+
+

+

target_act +
+[in thread send right] +Thread whose permission bitmap is to be set. +

+

device +
+[in device send right] +The device to which I/O instructions are to be +permitted. +
+

DESCRIPTION

+

+The i386_io_port_add 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. +

NOTES

+

+Normally, the thread must have called i386_io_port_add +for all devices to which it will execute I/O instructions. However, possessing +send rights to the iopl device port will cause the +iopl 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +i386_io_port_list, +i386_io_port_remove. 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 @@ -

i386_io_port_list

Function - List the devices that permit target thread to invoke operations.

SYNOPSIS

kern_return_t   i386_io_port_list
                (thread_act_t                        target_act,
                 device_list_t                      device_list);

PARAMETERS

target_act
[in thread send right] Thread whose permission list is to be returned.

device_list
[out pointer to dynamic array of device send rights] Device ports permitting I/O.

DESCRIPTION

The i386_io_port_list 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: i386_io_port_add, i386_io_port_remove. \ No newline at end of file +

i386_io_port_list

+
+

+Function - List the devices that permit target thread to invoke operations. +

SYNOPSIS

+
+kern_return_t   i386_io_port_list
+                (thread_act_t                        target_act,
+                 device_list_t                      device_list);
+
+

PARAMETERS

+
+

+

target_act +
+[in thread send right] +Thread whose permission list is to be returned. +

+

device_list +
+[out pointer to dynamic array of device send rights] +Device ports +permitting I/O. +
+

DESCRIPTION

+

+The i386_io_port_list 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +i386_io_port_add, +i386_io_port_remove. 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 @@ -

i386_io_port_remove

Function - Disable target thread's ability to invoke operations on the specified device.

SYNOPSIS

kern_return_t   i386_io_port_remove
                (thread_act_t                        target_act,
                 device_t                                device);

PARAMETERS

target_act
[in thread send right] Thread whose permission bitmap is to be cleared

device
[in device send right] Device whose permission is to be revoked

DESCRIPTION

The i386_io_port_remove function removes the specified device from the thread's I/O permission bitmap, thereby prohibiting I/O instructions being executed against the device.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: i386_io_port_add, i386_io_port_list. \ No newline at end of file +

i386_io_port_remove

+
+

+Function - Disable target thread's ability to invoke operations on the +specified device. +

SYNOPSIS

+
+kern_return_t   i386_io_port_remove
+                (thread_act_t                        target_act,
+                 device_t                                device);
+
+

PARAMETERS

+
+

+

target_act +
+[in thread send right] +Thread whose permission bitmap is to be cleared +

+

device +
+[in device send right] +Device whose permission is to be revoked +
+

DESCRIPTION

+

+The i386_io_port_remove function removes the specified +device from the +thread's I/O permission bitmap, thereby prohibiting I/O instructions being +executed against the device. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +i386_io_port_add, +i386_io_port_list. 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 @@ -

i386_set_ldt

Function - Set per-thread segment descriptors.

SYNOPSIS

kern_return_t   i386_set_ldt
                (thread_act_t                        target_act,
                 int                             first_selector,
                 descriptor_list_t                    desc_list);

PARAMETERS

target_act
[in thread send right] Thread whose segment descriptors are to be set.

first_selector
[in scalar] Selector value (segment register value) corresponding to the first segment whose descriptor is to be set.

desc_list
[pointer to in array of descriptor_t] Array of segment descriptors. The following forms are permitted:

  • Empty descriptor. The ACC_P flag (segment present) may or may not be set.

  • ACC_CALL_GATE--Converted into a system call gate. The ACC_P flag must be set.

All other descriptors must have both the ACC_P flag set and specify user mode access (ACC_PL_U).

  • ACC_DATA.

  • ACC_DATA_W.

  • ACC_DATA_E.

  • ACC_DATA_EW.

  • ACC_CODE.

  • ACC_CODE_R.

  • ACC_CODE_C.

  • ACC_CODE_CR.

  • ACC_CALL_GATE_16.

  • ACC_CALL_GATE.

DESCRIPTION

The i386_set_ldt 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: i386_get_ldt. \ No newline at end of file +

i386_set_ldt

+
+

+Function - Set per-thread segment descriptors. +

SYNOPSIS

+
+kern_return_t   i386_set_ldt
+                (thread_act_t                        target_act,
+                 int                             first_selector,
+                 descriptor_list_t                    desc_list);
+
+

PARAMETERS

+
+

+

target_act +
+[in thread send right] +Thread whose segment descriptors are to be set. +

+

first_selector +
+[in scalar] +Selector value (segment register value) corresponding to the +first segment whose descriptor is to be set. +

+

desc_list +
+[pointer to in array of descriptor_t] +Array of segment descriptors. The +following forms are permitted: +
    +

    +

  • +Empty descriptor. The ACC_P flag (segment present) may or may +not be set. +

    +

  • +ACC_CALL_GATE--Converted into a system call gate. The +ACC_P flag must be set. +
+

+All other descriptors must have both the ACC_P flag set and specify +user mode access (ACC_PL_U). +

    +

    +

  • +ACC_DATA. +

    +

  • +ACC_DATA_W. +

    +

  • +ACC_DATA_E. +

    +

  • +ACC_DATA_EW. +

    +

  • +ACC_CODE. +

    +

  • +ACC_CODE_R. +

    +

  • +ACC_CODE_C. +

    +

  • +ACC_CODE_CR. +

    +

  • +ACC_CALL_GATE_16. +

    +

  • +ACC_CALL_GATE. +
+
+

DESCRIPTION

+

+The i386_set_ldt 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +i386_get_ldt. 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 @@ - Mach Kernel Interface Reference Manual

Mach IPC Interface

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

Mach Message Queue Interface

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

Mach Message Queue Data Structures

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

Mach Lock-Set Interface

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

Mach Semaphore Interface

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

Mach Port Management Interface

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

Mach Port Data Structures

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

Mach Port Notification Callbacks

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

Mach Port Notification Callback Server Helpers

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

Mach Virtual Memory Interface

Mach Virtual Memory Address Space Manipulation Interface

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

Data Structures

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

External Memory Management Interface

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

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

Data Structures

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

External Memory Manager Interface Callbacks

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

EMMI Callback Server Helpers

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

Default Memory Management Interface

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

Process Management Interface

Task Interface

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

Task Data Structures

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

Thread Interface

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

Thread Data Structures

thread_basic_info - Defines basic information for a thread.

Thread Exception Callbacks

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

Thread Exception Callback Server Helpers

exc_server - Handle kernel-reported thread exception.

Scheduling Interface

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

Scheduling Data Structures

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

System Management Interface

Host Interface

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

Data Structures

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

Host Control Interface

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

Host Security Interface

host_security_create_task_token - Create a new task with an explicit security token.
host_security_set_task_token - Change the target task's security token.

Resource Accounting Interface

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

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

Processor Management Interface

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

Processor Data Structures

processor_basic_info - Defines the basic information about a processor.

Processor Set Interface

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

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

Processor Set Data Structures

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

Clock Interface

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

Clock Data Structures

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

Clock Interface Callbacks

clock_alarm_reply - Ring a preset alarm.

Clock Callback Server Helpers

clock_reply_server - Handle kernel-generated alarm.

Multi-Computer Support Interface

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

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

Machine Specific Interface

Intel 386 Support

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

PowerPC Support

\ No newline at end of file + + + + Mach Kernel Interface Reference Manual + + +

Mach IPC Interface

+
+

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

+ +

Mach Message Queue Interface

+
+

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

+Mach Message Queue Data Structures +

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

+
+ +

Mach Lock-Set Interface

+
+

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

+
+ +

Mach Semaphore Interface

+
+

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

+
+ +

Mach Port Management Interface

+
+

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

+Mach Port Data Structures +

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

+Mach Port Notification Callbacks +

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

+Mach Port Notification Callback Server Helpers +

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

+
+ +
+ +

Mach Virtual Memory Interface

+
+

Mach Virtual Memory Address Space Manipulation Interface

+
+

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

+Data Structures +

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

+
+ +

External Memory Management Interface

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

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

+Data Structures +

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

+External Memory Manager Interface Callbacks +

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

+EMMI Callback Server Helpers +

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

+
+ +

Default Memory Management Interface

+
+

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

+
+ +
+ +

Process Management Interface

+
+ +

Task Interface

+
+

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

+Task Data Structures +

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

+
+ +

Thread Interface

+
+

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

+Thread Data Structures +

+thread_basic_info - Defines basic information for a thread.
+

+Thread Exception Callbacks +

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

+Thread Exception Callback Server Helpers +

+exc_server - Handle kernel-reported thread exception.
+

+
+ +

Scheduling Interface

+
+

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

+Scheduling Data Structures +

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

+
+
+ +

System Management Interface

+
+ +

Host Interface

+
+

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

+Data Structures +

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

+
+ +

Host Control Interface

+
+

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

+
+ +

Host Security Interface

+
+

+host_security_create_task_token - Create a new task with an explicit security token.
+host_security_set_task_token - Change the target task's security token.
+

+
+ +

Resource Accounting Interface

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

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

+
+ +

Processor Management Interface

+
+

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

+Processor Data Structures +

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

+
+ +

Processor Set Interface

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

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

+Processor Set Data Structures +

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

+
+ +

Clock Interface

+
+

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

+Clock Data Structures +

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

+Clock Interface Callbacks +

+clock_alarm_reply - Ring a preset alarm.
+

+Clock Callback Server Helpers +

+ clock_reply_server - Handle kernel-generated alarm.
+

+
+ +

Multi-Computer Support Interface

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

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

+
+ +
+ +

Machine Specific Interface

+
+ +

Intel 386 Support

+
+

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

+
+ +

PowerPC Support

+
+

+

+
+ +
+ + + + + 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 @@ -

io_done_queue_create

Function - Create an io_done_queue kernel object.

SYNOPSIS

kern_return_t   io_done_queue_create
                (mach_port_t                               host,
                 mach_port_t                               queue);

PARAMETERS

host
[in host-name send right] The name (or control) port for the host on which the io_done_queue should be created.

queue
[out io-done-queue send right] The port referencing the created io_done_queue.

DESCRIPTION

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.

RETURN VALUES

KERN_INVALID_ARGUMENT
Invalid host parameter.

KERN_RESOURCE_SHORTAGE
Insufficient kernel resources to allocate kernel object.

RELATED INFORMATION

Functions: io_done_queue_terminate, io_done_queue_wait, device_read_async, device_read_async_inband, device_read_overwrite_async, device_write_async, device_write_async_inband. \ No newline at end of file +

io_done_queue_create

+
+

+Function - Create an io_done_queue kernel object. +

SYNOPSIS

+
+kern_return_t   io_done_queue_create
+                (mach_port_t                               host,
+                 mach_port_t                               queue);
+
+

PARAMETERS

+
+

+

host +
+[in host-name send right] The name (or control) port for the host on +which the io_done_queue should be created. +

+

queue +
+[out io-done-queue send right] The port referencing the created +io_done_queue. +
+

DESCRIPTION

+

+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. +

RETURN VALUES

+
+
KERN_INVALID_ARGUMENT +
+ Invalid host parameter. +

+

KERN_RESOURCE_SHORTAGE +
+ Insufficient kernel resources to allocate kernel object. +
+

RELATED INFORMATION

+

+Functions: +io_done_queue_terminate, +io_done_queue_wait, +device_read_async, +device_read_async_inband, +device_read_overwrite_async, +device_write_async, +device_write_async_inband. 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 @@ -

io_done_queue_terminate

Function - Terminate an io_done_queue kernel object.

SYNOPSIS

#include<device/device.h>

kern_return_t	io_done_queue_terminate
		(mach_port_t	queue);

PARAMETERS

queue
[in io-done-queue send right] The port referencing the io_done_queue to be destroyed.

DESCRIPTION

The io_done_queue_terminate function is called to destroy a previous instatiation of the kernel object supporting asynchronous read/write operations on a device.

RETURN VALUES

KERN_INVALID_ARGUMENT
Invalid queue parameter.

RELATED INFORMATION

Functions: io_done_queue_create, io_done_queue_wait, device_read_async, device_read_async_inband, device_read_overwrite_async, device_write_async, device_write_async_inband. \ No newline at end of file +

io_done_queue_terminate

+
+

+Function - Terminate an io_done_queue kernel object. +

SYNOPSIS

+
+#include<device/device.h>
+
+kern_return_t	io_done_queue_terminate
+		(mach_port_t	queue);
+
+

PARAMETERS

+
+

+

queue +
+[in io-done-queue send right] The port referencing the io_done_queue +to be destroyed. +
+

DESCRIPTION

+

+The io_done_queue_terminate function is called to destroy a previous +instatiation of the kernel object supporting asynchronous read/write +operations on a device. +

RETURN VALUES

+
+
KERN_INVALID_ARGUMENT +
+ Invalid queue parameter. +

+

+

RELATED INFORMATION

+

+Functions: +io_done_queue_create, +io_done_queue_wait, +device_read_async, +device_read_async_inband, +device_read_overwrite_async, +device_write_async, +device_write_async_inband. 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 @@ -

io_done_queue_wait

System Trap - Wait on an io_done_queue kernel object.

SYNOPSIS

kern_return_t	io_done_queue_wait
		(mach_port_t             queue,
		io_done_result_t       *result);

PARAMETERS

queue
[in io-done-queue send right] The port referencing the io_done_queue to be destroyed.

result
[out structure] The data structure to be filled in with the completion status of the I/O operation.

DESCRIPTION

The io_done_queue_wait interface is called to obtain the results of a previously requested asynchronous I/O operation. For each io_done_queue_wait 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 io_done_result's) on the completion queue and posts a wakeup on the queue for each I/O completion. Completion processing previously done by the mKernel io_done thread is now done by the task thread when it awakens.

RETURN VALUES

KERN_TERMINATED
Stale io_done_queue handle.

KERN_INVALID_ARGUMENT
Invalid queue parameter.

KERN_INVALID_ARGUMENT
The result parameter is a bad address.

RELATED INFORMATION

Functions: io_done_queue_create, io_done_queue_wait, device_read_async, device_read_async_inband, device_read_overwrite_async, device_write_async, device_write_async_inband. \ No newline at end of file +

io_done_queue_wait

+
+

+System Trap - Wait on an io_done_queue kernel object. +

SYNOPSIS

+
+kern_return_t	io_done_queue_wait
+		(mach_port_t             queue,
+		io_done_result_t       *result);
+
+

PARAMETERS

+
+

+

queue +
+[in io-done-queue send right] The port referencing the io_done_queue +to be destroyed. +

+

result +
+[out structure] The data structure to be filled in with the completion +status of the I/O operation. +
+

DESCRIPTION

+

+The io_done_queue_wait interface is called to obtain the results of a +previously requested asynchronous I/O operation. For each +io_done_queue_wait 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 io_done_result's) on the completion queue and posts a wakeup +on the queue for each I/O completion. Completion processing previously +done by the mKernel io_done thread is now done by the task thread when +it awakens. +

RETURN VALUES

+
+
KERN_TERMINATED +
+ Stale io_done_queue handle. +

+ +

KERN_INVALID_ARGUMENT +
+ Invalid queue parameter. +

+

KERN_INVALID_ARGUMENT +
+ The result parameter is a bad address. +

+

+

RELATED INFORMATION

+

+Functions: +io_done_queue_create, +io_done_queue_wait, +device_read_async, +device_read_async_inband, +device_read_overwrite_async, +device_write_async, +device_write_async_inband. 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 @@ -

kernel_resource_sizes

Structure - Used to present the sizes of kernel's major structures.

SYNOPSIS

struct kernel_resource_sizes
{
       vm_size_t               task;
       vm_size_t             thread;
       vm_size_t               port;
       vm_size_t      memory_region;
       vm_size_t      memory_object;
};

typedef struct kernel_resource_sizes* kernel_resource_sizes_t;

FIELDS

task
Space consumed by an empty task.

thread
Space consumed by a thread.

port
Space consumed by a port with an empty message queue.

memory_region
Space consumed by each distinct memory region (as reported by vm_region) in a task's address space.

memory_object
Space consumed to manage a memory object with no resident pages or copy objects.

DESCRIPTION

The kernel_resource_sizes structure defines the sizes of significant kernel structures.

RELATED INFORMATION

Functions: host_info. \ No newline at end of file +

kernel_resource_sizes

+
+

+Structure - Used to present the sizes of kernel's major structures. +

SYNOPSIS

+
+struct kernel_resource_sizes
+{
+       vm_size_t               task;
+       vm_size_t             thread;
+       vm_size_t               port;
+       vm_size_t      memory_region;
+       vm_size_t      memory_object;
+};
+
+typedef struct kernel_resource_sizes* kernel_resource_sizes_t;
+
+

FIELDS

+
+
task +
+Space consumed by an empty task. +

+

thread +
+Space consumed by a thread. +

+

port +
+Space consumed by a port with an empty message queue. +

+

memory_region +
+Space consumed by each distinct memory region (as reported by +vm_region) in a task's address space. +

+

memory_object +
+Space consumed to manage a memory object with no resident pages or +copy objects. +
+

DESCRIPTION

+

+The kernel_resource_sizes structure defines the sizes +of significant kernel +structures. +

RELATED INFORMATION

+

+Functions: +host_info. 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 @@ -

ledger_create

Function - Create a subordinate ledger.

SYNOPSIS

kern_return_t   ledger_create
                (ledger_port_t                    parent_ledger,
                 ledger_port_t                    ledger_ledger,
                 ledger_port_t                     child_ledger,
                 ledger_item_t                         transfer);

PARAMETERS

parent_ledger
[in ledger send right] The parent ledger.

ledger_ledger
[in ledger send right] The wired kernel memory ledger providing the space from which the ledger itself is drawn.

child_ledger
[out ledger send right] The new child ledger, of the same resource type as the parent ledger.

transfer
[in scalar] The resource amount to transfer to the new ledger.

DESCRIPTION

The ledger_create function creates a subordinate ledger. Resource limits can be transferred from the parent ledger. The child ledger itself is accounted against the ledger_ledger. A new ledger inherits the remote service port.

NOTES

This interface is not implemented in OSF/1 R1.3.

A ledger limit of LEDGER_ITEM_INFINITE allows any amount (even infinity) to be withdrawn. The root ledger has such a limit.

RETURN VALUES

KERN_RESOURCE_SHORTAGE
Transferring the resources would cause the parent ledger to exceed its limits.

KERN_INVALID_LEDGER
ledger_ledger is not a wired kernel memory ledger.

RELATED INFORMATION

Functions: ledger_transfer, ledger_terminate, ledger_read, ledger_set_remote. \ No newline at end of file +

ledger_create

+
+

+Function - Create a subordinate ledger. +

SYNOPSIS

+
+kern_return_t   ledger_create
+                (ledger_port_t                    parent_ledger,
+                 ledger_port_t                    ledger_ledger,
+                 ledger_port_t                     child_ledger,
+                 ledger_item_t                         transfer);
+
+

PARAMETERS

+
+

+

parent_ledger +
+[in ledger send right] +The parent ledger. +

+

ledger_ledger +
+[in ledger send right] +The wired kernel memory ledger providing the +space from which the ledger itself is drawn. +

+

child_ledger +
+[out ledger send right] +The new child ledger, of the same resource type +as the parent ledger. +

+

transfer +
+[in scalar] +The resource amount to transfer to the new ledger. +
+

DESCRIPTION

+

+The ledger_create function creates a subordinate ledger. +Resource limits can be +transferred from the parent ledger. The child ledger itself +is accounted against +the ledger_ledger. A new ledger inherits the remote service port. +

NOTES

+

+This interface is not implemented in OSF/1 R1.3. +

+A ledger limit of LEDGER_ITEM_INFINITE allows any amount (even +infinity) to be withdrawn. The root ledger has such a limit. +

RETURN VALUES

+
+

+

KERN_RESOURCE_SHORTAGE +
+Transferring the resources would cause the parent ledger to exceed its +limits. +

+

KERN_INVALID_LEDGER +
+ledger_ledger is not a wired kernel memory ledger. +
+

RELATED INFORMATION

+

+Functions: +ledger_transfer, +ledger_terminate, +ledger_read, +ledger_set_remote. 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 @@ -

ledger_get_remote

Function - Return send right to specified host's remote ledger port.

SYNOPSIS

kern_return_t   ledger_get_remote
                (ledger_port_t                           ledger,
                 host_t                               host_name,
                 ledger                            service_port);


kern_return_t   ledger_return_remote
                (ledger_port_t                           ledger,
                 host_t                               host_name,
                 ledger                            service_port);

PARAMETERS

ledger
[in ledger send right] The ledger whose service port is desired.

host_name
[in host-name send right] The name for the host requesting the service port.

service_port
[out ledger-service send right] The ledger service port.

DESCRIPTION

The ledger_get_remote function returns the remote ledger service port for the ledger

NOTES

This interface is not implemented in OSF/1 R1.3.

This mechanism supports distributed resource ledgers in the following way:

With ledger_set_remote, a ledger is assigned a remote ledger service port.
This ledger is used as the ledger for a create operation. If the ledger is local to the target kernel, all is fine.
For a non-local creation, the target kernel sees that the supplied ledger is not a local ledger. The kernel sends a ledger_get_remote message to it, including the host name.
The (remote) ledger receives this message, ignores the host name and returns the remote ledger service port.
Assuming that the remote ledger service port is not a local ledger, the kernel sends a ledger_get_remote message to this service port.
A server receives this request (with the ledger_return_remote 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.
The port for a ledger on the target kernel is sent to that kernel and used.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: ledger_create, ledger_set_remote. \ No newline at end of file +

ledger_get_remote

+
+

+Function - Return send right to specified host's remote ledger port. +

SYNOPSIS

+
+kern_return_t   ledger_get_remote
+                (ledger_port_t                           ledger,
+                 host_t                               host_name,
+                 ledger                            service_port);
+
+
+kern_return_t   ledger_return_remote
+                (ledger_port_t                           ledger,
+                 host_t                               host_name,
+                 ledger                            service_port);
+
+

PARAMETERS

+
+

+

ledger +
+[in ledger send right] +The ledger whose service port is desired. +

+

host_name +
+[in host-name send right] +The name for the host requesting the service +port. +

+

service_port +
+[out ledger-service send right] +The ledger service port. +
+

DESCRIPTION

+

+The ledger_get_remote function returns the remote ledger +service port for the +ledger +

NOTES

+

+This interface is not implemented in OSF/1 R1.3. +

+This mechanism supports distributed resource ledgers in the following way: +

+
+With ledger_set_remote, a ledger is assigned a remote +ledger service port. +
+This ledger is used as the ledger for a create operation. +If the ledger is local to the target kernel, all is fine. +
+For a non-local creation, the target kernel sees that the supplied +ledger is not +a local ledger. The kernel sends a ledger_get_remote message to it, +including the host name. +
+The (remote) ledger receives this message, ignores the host name and returns +the remote ledger service port. +
+Assuming that the remote ledger service port is not a local ledger, the kernel +sends a ledger_get_remote message to this service port. +
+A server receives this request (with the ledger_return_remote +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. +
+The port for a ledger on the target kernel is sent to that kernel and used. +
+

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +ledger_create, +ledger_set_remote. 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 @@ -

ledger_read

Function - Return the ledger limit and balance.

SYNOPSIS

kern_return_t   ledger_read
                (ledger_port_t                           ledger,
                 ledger_item_t                          balance,
                 ledger_item_t                          maximum);

PARAMETERS

ledger
[in ledger send right] The ledger to read

balance
[out scalar] The current usage

maximum
[out scalar] The resource limit

DESCRIPTION

The ledger_read function returns the current balance and limit in a ledger.

NOTES

This interface is not implemented in OSF/1 R1.3.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: ledger_create, ledger_terminate, ledger_transfer. \ No newline at end of file +

ledger_read

+
+

+Function - Return the ledger limit and balance. +

SYNOPSIS

+
+kern_return_t   ledger_read
+                (ledger_port_t                           ledger,
+                 ledger_item_t                          balance,
+                 ledger_item_t                          maximum);
+
+

PARAMETERS

+
+

+

ledger +
+[in ledger send right] +The ledger to read +

+

balance +
+[out scalar] +The current usage +

+

maximum +
+[out scalar] +The resource limit +
+

DESCRIPTION

+

+The ledger_read function returns the current balance +and limit in a ledger. +

NOTES

+

+This interface is not implemented in OSF/1 R1.3. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +ledger_create, +ledger_terminate, +ledger_transfer. + + 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 @@ -

ledger_set_remote

Function - Set this host's remote ledger port.

SYNOPSIS

kern_return_t   ledger_set_remote
                (ledger_port_t                           ledger,
                 ledger_port_t                     service_port);

PARAMETERS

ledger
[in ledger send right] The ledger whose service port is to be set.

service_port
[in ledger-service send right] The ledger service port

DESCRIPTION

The ledger_set_remote function sets the remote ledger service port for the ledger. This is the port the ledger will return for ledger_get_remote requests.

NOTES

This interface is not implemented in OSF/1 R1.3.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: ledger_create, ledger_get_remote. \ No newline at end of file +

ledger_set_remote

+
+

+Function - Set this host's remote ledger port. +

SYNOPSIS

+
+kern_return_t   ledger_set_remote
+                (ledger_port_t                           ledger,
+                 ledger_port_t                     service_port);
+
+

PARAMETERS

+
+

+

ledger +
+[in ledger send right] +The ledger whose service port is to be set. +

+

service_port +
+[in ledger-service send right] +The ledger service port +
+

DESCRIPTION

+

+The ledger_set_remote function sets the remote ledger service port +for the ledger. This is the port the ledger will return for +ledger_get_remote requests. +

NOTES

+

+This interface is not implemented in OSF/1 R1.3. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +ledger_create, +ledger_get_remote. 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 @@ -

ledger_terminate

Function - Destroy a ledger.

SYNOPSIS

kern_return_t   ledger_terminate
                (ledger_port_t                           ledger);

PARAMETERS

ledger
[in ledger send right] The ledger to destroy

DESCRIPTION

The ledger_terminate 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.

NOTES

This interface is not implemented in OSF/1 R1.3.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: ledger_create, ledger_read, ledger_transfer. \ No newline at end of file +

ledger_terminate

+
+

+Function - Destroy a ledger. +

SYNOPSIS

+
+kern_return_t   ledger_terminate
+                (ledger_port_t                           ledger);
+
+

PARAMETERS

+
+

+

ledger +
+[in ledger send right] +The ledger to destroy +
+

DESCRIPTION

+

+The ledger_terminate 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. +

NOTES

+

+This interface is not implemented in OSF/1 R1.3. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +ledger_create, +ledger_read, +ledger_transfer. 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 @@ -

ledger_transfer

Function - Transfer resources from a parent ledger to a child.

SYNOPSIS

kern_return_t   ledger_transfer
                (ledger_port_t                    parent_ledger,
                 ledger_port_t                     child_ledger,
                 ledger_item_t                         transfer);

PARAMETERS

parent_ledger
[in ledger send right] The parent ledger

child_ledger
[in ledger send right] The child ledger

transfer
[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.

DESCRIPTION

The ledger_transfer function transfers resources from a parent to a child ledger.

NOTES

This interface is not implemented in OSF/1 R1.3.

RETURN VALUES

KERN_RESOURCE_SHORTAGE
Transferring the resources would cause one ledger to exceed its limit.

RELATED INFORMATION

Functions: ledger_create, ledger_terminate, ledger_read. \ No newline at end of file +

ledger_transfer

+
+

+Function - Transfer resources from a parent ledger to a child. +

SYNOPSIS

+
+kern_return_t   ledger_transfer
+                (ledger_port_t                    parent_ledger,
+                 ledger_port_t                     child_ledger,
+                 ledger_item_t                         transfer);
+
+

PARAMETERS

+
+

+

parent_ledger +
+[in ledger send right] +The parent ledger +

+

child_ledger +
+[in ledger send right] +The child ledger +

+

transfer +
+[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. +
+

DESCRIPTION

+

+The ledger_transfer function transfers resources from +a parent to a child ledger. +

NOTES

+

+This interface is not implemented in OSF/1 R1.3. +

RETURN VALUES

+
+

+

KERN_RESOURCE_SHORTAGE +
+Transferring the resources would cause one ledger to exceed its limit. +
+

RELATED INFORMATION

+

+Functions: +ledger_create, +ledger_terminate, +ledger_read. 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 @@ -

lock_acquire

Function - Acquire access rights to a lock.

SYNOPSIS

kern_return_t   lock_acquire
                (lock_set_t                            lock_set,
                 int                                    lock_id);

PARAMETERS

lock_set
[in send right] The port naming the lock set which represents the lock.

lock_id
[in scalar] The lock, represented by the lock set, to be acquired.

DESCRIPTION

The lock_acquire 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.

RETURN VALUES

KERN_SUCCESS
The lock was acquired.

KERN_INVALID_ARGUMENT
The specified lock set is invalid, or the lock id is out of range.

KERN_LOCK_UNSTABLE
The acquired lock has an unstable state.

KERN_LOCK_SET_DESTROYED
The specified lock has been destroyed.

KERN_ABORTED
While blocked to wait for the specified lock to become available, the calling thread was awoken by an unrelated event, such as thread termination.

RELATED INFORMATION

Functions: lock_release, lock_try, lock_handoff, lock_handoff_accept, lock_make_stable, lock_set_create, lock_set_destroy. \ No newline at end of file +

lock_acquire

+
+

+Function - Acquire access rights to a lock. +

SYNOPSIS

+
+kern_return_t   lock_acquire
+                (lock_set_t                            lock_set,
+                 int                                    lock_id);
+
+

PARAMETERS

+
+

+

lock_set +
+[in send right] The port naming the lock set which represents the +lock. +

+

lock_id +
+[in scalar] The lock, represented by the lock set, to be acquired. +
+

DESCRIPTION

+

+The lock_acquire 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. +

RETURN VALUES

+
+

+

KERN_SUCCESS +
+The lock was acquired. +

+

KERN_INVALID_ARGUMENT +
+The specified lock set is invalid, or the lock id is out of range. +

+

KERN_LOCK_UNSTABLE +
+The acquired lock has an unstable state. +

+

KERN_LOCK_SET_DESTROYED +
+The specified lock has been destroyed. +

+

KERN_ABORTED +
+While blocked to wait for the specified lock to become available, the calling + thread was awoken by an unrelated event, such as thread termination. +
+

RELATED INFORMATION

+

+Functions: +lock_release, +lock_try, +lock_handoff, +lock_handoff_accept, +lock_make_stable, +lock_set_create, +lock_set_destroy. 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 @@ -

lock_handoff

Function - Hand-off ownership of a lock.

SYNOPSIS

kern_return_t   lock_handoff
                (lock_set_t                            lock_set,
                 int                                    lock_id);

PARAMETERS

lock_set
[in send right] The port naming the lock set which represents the lock.

lock_id
[in scalar] The lock, represented by the lock set, to be handed off.

DESCRIPTION

The lock_handoff 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.

RETURN VALUES

KERN_INVALID_ARGUMENT
The specified lock_set is invalid, or the lock_id is out of range.

KERN_INVALID_RIGHT
The calling thread does not own the lock being handed off.

KERN_SUCCESS
The lock hand-off was successful.

KERN_LOCK_SET_DESTROYED
The specified lock has been destroyed.

KERN_ABORTED
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.

RELATED INFORMATION

Functions: lock_acquire, lock_release, lock_try, lock_handoff_accept, lock_make_stable, lock_set_create, lock_set_destroy. \ No newline at end of file +

lock_handoff

+
+

+Function - Hand-off ownership of a lock. +

SYNOPSIS

+
+kern_return_t   lock_handoff
+                (lock_set_t                            lock_set,
+                 int                                    lock_id);
+
+

PARAMETERS

+
+

+

lock_set +
+[in send right] The port naming the lock set which represents the +lock. +

+

lock_id +
+[in scalar] The lock, represented by the lock set, to be handed off. +
+

DESCRIPTION

+

+The lock_handoff 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. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+The specified lock_set is invalid, or the lock_id is out of range. +

+

KERN_INVALID_RIGHT +
+The calling thread does not own the lock being handed off. +

+

KERN_SUCCESS +
+The lock hand-off was successful. +

+

KERN_LOCK_SET_DESTROYED +
+The specified lock has been destroyed. +

+

KERN_ABORTED +
+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. +
+

RELATED INFORMATION

+

+Functions: +lock_acquire, +lock_release, +lock_try, +lock_handoff_accept, +lock_make_stable, +lock_set_create, +lock_set_destroy. 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 @@ -

lock_handoff_accept

Function - Accept a lock hand-off.

SYNOPSIS

kern_return_t   lock_handoff_accept
                (lock_set_t                            lock_set,
                 int                                    lock_id);

PARAMETERS

lock_set
[in send right] The port naming the lock set which represents the lock.

lock_id
[in scalar] The lock, represented by the lock set, that is the object of the handoff operation.

DESCRIPTION

The lock_handoff_accept 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.

RETURN VALUES

KERN_ALREADY_WAITING
Another thread is already waiting for a hand-off of this lock.

KERN_INVALID_ARGUMENT
The specified lock_set is invalid, or the lock_id is out of range.

KERN_SUCCESS
The lock hand-off was successful.

KERN_LOCK_UNSTABLE
The acquired lock has an unstable state.

KERN_LOCK_SET_DESTROYED
The specified lock has been destroyed.

KERN_ABORTED
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.

RELATED INFORMATION

Functions: lock_acquire, lock_release, lock_try, lock_handoff. \ No newline at end of file +

lock_handoff_accept

+
+

+Function - Accept a lock hand-off. +

SYNOPSIS

+
+kern_return_t   lock_handoff_accept
+                (lock_set_t                            lock_set,
+                 int                                    lock_id);
+
+

PARAMETERS

+
+

+

lock_set +
+[in send right] The port naming the lock set which represents the +lock. +

+

lock_id +
+[in scalar] The lock, represented by the lock set, that is the object +of the handoff operation. +
+

DESCRIPTION

+

+The lock_handoff_accept 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. +

RETURN VALUES

+
+

+

KERN_ALREADY_WAITING +
+Another thread is already waiting for a hand-off of this lock. +

+

KERN_INVALID_ARGUMENT +
+The specified lock_set is invalid, or the lock_id is out of range. +

+

KERN_SUCCESS +
+The lock hand-off was successful. +

+

KERN_LOCK_UNSTABLE +
+The acquired lock has an unstable state. +

+

KERN_LOCK_SET_DESTROYED +
+The specified lock has been destroyed. +

+

KERN_ABORTED +
+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. +
+

RELATED INFORMATION

+

+Functions: +lock_acquire, +lock_release, +lock_try, +lock_handoff. 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 @@ -

lock_make_stable

Function - Stabilize the state of the specified lock.

SYNOPSIS

kern_return_t   lock_make_stable
                (lock_set_t                            lock_set,
                 int                                    lock_id);

PARAMETERS

lock_set
[in send right] The port naming the lock set which represents the lock.

lock_id
[in scalar] The lock, represented by the lock set, to be stabilized.

DESCRIPTION

The lock_make_stable function clears the specified lock's unstable state, making the lock's state stable again.

RETURN VALUES

KERN_INVALID_ARGUMENT
The specified lock set is invalid, or the lock id is out of range.

KERN_INVALID_RIGHT
The caller does not own the specified lock.

KERN_SUCCESS
The lock's state was stabilized.

KERN_LOCK_SET_DESTROYED
The specified lock has been destroyed.

RELATED INFORMATION

Functions: lock_acquire, lock_release, lock_try, lock_handoff, lock_handoff_accept, lock_set_create, lock_set_destroy. \ No newline at end of file +

lock_make_stable

+
+

+Function - Stabilize the state of the specified lock. +

SYNOPSIS

+
+kern_return_t   lock_make_stable
+                (lock_set_t                            lock_set,
+                 int                                    lock_id);
+
+

PARAMETERS

+
+

+

lock_set +
+[in send right] The port naming the lock set which represents the +lock. +

+

lock_id +
+[in scalar] The lock, represented by the lock set, to be stabilized. +
+

DESCRIPTION

+

+The lock_make_stable function clears the specified lock's unstable +state, making the lock's state stable again. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+The specified lock set is invalid, or the lock id is out of range. +

+

KERN_INVALID_RIGHT +
+ The caller does not own the specified lock. +

+

KERN_SUCCESS +
+The lock's state was stabilized. +

+

KERN_LOCK_SET_DESTROYED +
+The specified lock has been destroyed. +
+

RELATED INFORMATION

+

+Functions: +lock_acquire, +lock_release, +lock_try, +lock_handoff, +lock_handoff_accept, +lock_set_create, +lock_set_destroy. 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 @@ -

lock_release

Function - Release ownership of a lock.

SYNOPSIS

kern_return_t   lock_release
                (lock_set_t                            lock_set,
                 int                                    lock_id);

PARAMETERS

lock_set
[in send right] The port naming the lock set which represents the lock.

lock_id
[in scalar] The lock, represented by the lock set, to be released.

DESCRIPTION

The lock_release function release the ownership of the specified lock. If the calling thread does not own the lock then the call will fail.

RETURN VALUES

KERN_INVALID_ARGUMENT
The specified lock_set is invalid, or the lock_id is out of range.

KERN_INVALID_RIGHT
The specified task does not own the specified lock.

KERN_SUCCESS
The ownership of the lock was released.

KERN_LOCK_SET_DESTROYED
The specified lock has been destroyed.

RELATED INFORMATION

Functions: lock_acquire, lock_make_stable, lock_try, lock_handoff, lock_handoff_accept, lock_set_create, lock_set_destroy. \ No newline at end of file +

lock_release

+
+

+Function - Release ownership of a lock. +

SYNOPSIS

+
+kern_return_t   lock_release
+                (lock_set_t                            lock_set,
+                 int                                    lock_id);
+
+

PARAMETERS

+
+

+

lock_set +
+[in send right] The port naming the lock set which represents the +lock. +

+

lock_id +
+[in scalar] The lock, represented by the lock set, to be released. +
+

DESCRIPTION

+

+The lock_release function release the ownership of the specified lock. +If the calling thread does not own the lock then the call will fail. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+The specified lock_set is invalid, or the lock_id is out of range. +

+

KERN_INVALID_RIGHT +
+ The specified task does not own the specified lock. +

+

KERN_SUCCESS +
+The ownership of the lock was released. +

+

KERN_LOCK_SET_DESTROYED +
+The specified lock has been destroyed. +
+

RELATED INFORMATION

+

+Functions: +lock_acquire, +lock_make_stable, +lock_try, +lock_handoff, +lock_handoff_accept, +lock_set_create, +lock_set_destroy. 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 @@ -

lock_set_create

Function - Create a new lock set.

SYNOPSIS

kern_return_t   lock_set_create
                (task_t                                    task,
                 lock_set_t                            lock_set,
                 int                                      locks,
                 int                                     policy);

PARAMETERS

task
The task receiving the send right to the newly created lock set.

lock_set
[out send right] The port naming the lock set which represents the lock.

locks
[in scalar] The number of locks the lock set will represent (must be a positive value).

policy
[in scalar] The blocked thread wakeup policy for the newly created lock set. Valid policies are:

SYNC_POLICY_FIFO
a first-in-first-out policy for scheduling thread wakeup.

SYNC_POLICY_FIXED_PRIORITY
a fixed priority policy for scheduling thread wakeup.

DESCRIPTION

The lock_set_create 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.

RETURN VALUES

KERN_SUCCESS
The lock set was created.

KERN_INVALID_ARGUMENT
Either the task or policy argument is invalid, or the locks argument has a value that is less than or equal to zero.

KERN_RESOURCE_SHORTAGE
The kernel could not allocate the lock set.

RELATED INFORMATION

Functions: lock_acquire, lock_make_stable, lock_try, lock_handoff, lock_handoff_accept, lock_try, lock_set_destroy. \ No newline at end of file +

lock_set_create

+
+

+Function - Create a new lock set. +

SYNOPSIS

+
+kern_return_t   lock_set_create
+                (task_t                                    task,
+                 lock_set_t                            lock_set,
+                 int                                      locks,
+                 int                                     policy);
+
+

PARAMETERS

+
+

+

task +
+The task receiving the send right to the newly created lock set. +

+

lock_set +
+[out send right] The port naming the lock set which represents the lock. +

+

locks +
+[in scalar] The number of locks the lock set will represent (must be a positive value). +

+

policy +
+[in scalar] The blocked thread wakeup policy for the newly created lock set. Valid policies are: +
+

+

SYNC_POLICY_FIFO +
+a first-in-first-out policy for scheduling thread wakeup. +

+

SYNC_POLICY_FIXED_PRIORITY +
+a fixed priority policy for scheduling thread wakeup. +
+
+

DESCRIPTION

+

+The lock_set_create 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. +

RETURN VALUES

+
+

+

KERN_SUCCESS +
+The lock set was created. +

+

KERN_INVALID_ARGUMENT +
+Either the task or policy argument is invalid, or the locks argument +has a value that is less than or equal to zero. +

+

KERN_RESOURCE_SHORTAGE +
+The kernel could not allocate the lock set. +
+

RELATED INFORMATION

+

+Functions: +lock_acquire, +lock_make_stable, +lock_try, +lock_handoff, +lock_handoff_accept, +lock_try, +lock_set_destroy. 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 @@ -

lock_set_destroy

Function - Destroy a lock set and its associated locks.

SYNOPSIS

kern_return_t   lock_set_destroy
                (task_t                                    task,
                 lock_set_t                            lock_set);

PARAMETERS

task
The task associated with the lock set.

lock_set
[in send right] The port naming the lock set being destroyed.

DESCRIPTION

The lock_set_destroy 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 lock_set_destroy function will only succeed if the specified task is associated with the specified lock set.

RETURN VALUES

KERN_INVALID_ARGUMENT
The specified lock set or task is invalid.

KERN_INVALID_RIGHT
The specified task does not own the specified lock set.

KERN_LOCK_SET_DESTROYED
The specified lock set does not exist.

KERN_SUCCESS
The lock set was destroyed.

RELATED INFORMATION

Functions: lock_acquire, lock_make_stable, lock_try, lock_handoff, lock_handoff_accept, lock_try, lock_set_create. \ No newline at end of file +

lock_set_destroy

+
+

+Function - Destroy a lock set and its associated locks. +

SYNOPSIS

+
+kern_return_t   lock_set_destroy
+                (task_t                                    task,
+                 lock_set_t                            lock_set);
+
+

PARAMETERS

+
+

+

task +
+The task associated with the lock set. +

+

lock_set +
+[in send right] The port naming the lock set being destroyed. +
+

DESCRIPTION

+

+The lock_set_destroy 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 lock_set_destroy function will only succeed if the +specified task is associated with the specified lock set. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+The specified lock set or task is invalid. +

+

KERN_INVALID_RIGHT +
+ The specified task does not own the specified lock set. +

+

KERN_LOCK_SET_DESTROYED +
+ The specified lock set does not exist. +

+

KERN_SUCCESS +
+The lock set was destroyed. +
+

RELATED INFORMATION

+

+Functions: +lock_acquire, +lock_make_stable, +lock_try, +lock_handoff, +lock_handoff_accept, +lock_try, +lock_set_create. 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 @@ -

lock_try

Function - Attempt to acquire access rights to a lock.

SYNOPSIS

kern_return_t   lock_try
                (lock_set_t                            lock_set,
                 int                                    lock_id);

PARAMETERS

lock_set
[in send right] The port naming the lock set which represents the lock.

lock_id
[in scalar] The lock, represented by the lock set, to be acquired.

DESCRIPTION

The lock_try function attempts to acquire the specified lock without blocking. The return value indicates whether the lock was acquired.

RETURN VALUES

KERN_INVALID_ARGUMENT
The specified lock_set is invalid, or the lock_id is out of range.

KERN_SUCCESS
The lock was acquired.

KERN_LOCK_UNSTABLE
The acquired lock has an unstable state.

KERN_LOCK_SET_DESTROYED
The specified lock has been destroyed.

KERN_LOCK_OWNED
Another thread currently owns the requested lock.

KERN_LOCK_OWNED_SELF
The calling thread already owns the lock.

RELATED INFORMATION

Functions: lock_acquire, lock_make_stable, lock_release, lock_handoff, lock_handoff_accept, lock_set_create, lock_set_destroy. \ No newline at end of file +

lock_try

+
+

+Function - Attempt to acquire access rights to a lock. +

SYNOPSIS

+
+kern_return_t   lock_try
+                (lock_set_t                            lock_set,
+                 int                                    lock_id);
+
+

PARAMETERS

+
+

+

lock_set +
+[in send right] The port naming the lock set which represents the lock. +

+

lock_id +
+[in scalar] The lock, represented by the lock set, to be acquired. +
+

DESCRIPTION

+

+The lock_try function attempts to acquire the specified lock without +blocking. The return value indicates whether the lock was acquired. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+The specified lock_set is invalid, or the lock_id is out of range. +

+

KERN_SUCCESS +
+The lock was acquired. +

+

KERN_LOCK_UNSTABLE +
+The acquired lock has an unstable state. +

+

KERN_LOCK_SET_DESTROYED +
+The specified lock has been destroyed. +

+

KERN_LOCK_OWNED +
+Another thread currently owns the requested lock. +

+

KERN_LOCK_OWNED_SELF +
+The calling thread already owns the lock. +
+

RELATED INFORMATION

+

+Functions: +lock_acquire, +lock_make_stable, +lock_release, +lock_handoff, +lock_handoff_accept, +lock_set_create, +lock_set_destroy. 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 @@ -

mach_host_self

System Trap - Returns the host self port

SYNOPSIS

host_name_port_t   mach_host_self( void );

PARAMETERS

None.

DESCRIPTION

The mach_host_self 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.

RETURN VALUES

[host-self send right] Send rights to the host's name port.

RELATED INFORMATION

Functions: host_info, task_set_special_port. \ No newline at end of file +

mach_host_self

+
+

+System Trap - Returns the host self port +

SYNOPSIS

+
+host_name_port_t   mach_host_self( void );
+
+

PARAMETERS

+

+None. + +

DESCRIPTION

+

+The mach_host_self 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. + +

RETURN VALUES

+

+[host-self send right] Send rights to the host's name port. + +

RELATED INFORMATION

+

+Functions: +host_info, +task_set_special_port. 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 @@ -

mach_msg

System Trap / Function - Send and/or receive a message from the target port.

SYNOPSIS

mach_msg_return_t   mach_msg
                    (mach_msg_header_t                msg,
                     mach_msg_option_t             option,
                     mach_msg_size_t            send_size,
                     mach_msg_size_t        receive_limit,
                     mach_port_t             receive_name,
                     mach_msg_timeout_t           timeout,
                     mach_port_t                   notify);

mach_msg_return_t   mach_msg_overwrite
                    (mach_msg_header_t*          send_msg,
                     mach_msg_option_t             option,
                     mach_msg_size_t            send_size,
                     mach_msg_size_t        receive_limit,
                     mach_port_t             receive_name,
                     mach_msg_timeout_t           timeout,
                     mach_port_t                   notify,
                     mach_msg_header_t       *receive_msg,
                     mach_msg_size_t     receive_msg_size);

PARAMETERS

msg
[pointer to in/out structure containing random and reply rights] A message buffer used by mach_msg both for send and receive. This must be naturally aligned.

send_msg
[pointer to in structure containing random and reply rights] The mes- sage buffer to be sent. This must be naturally aligned.

option
[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.

send_size
[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.

receive_limit
[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.

receive_name
[in random right] When receiving a message, specifies the port or port set. Otherwise MACH_PORT_NULL should be supplied.

timeout
[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.

notify
[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.

receive_msg
[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 (mach_msg), 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.

receive_msg_size
[in scalar] When using the MACH_RCV_OVERWRITE option, specifies the size (in bytes) of the receive "message" that is to be used by mach_msg to indicate the disposition of received out-of-line regions.

DESCRIPTION

The mach_msg system call sends and receives Mach messages. Mach messages contain data, which can include port rights and addresses of large regions of memory. mach_msg 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 send_size 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.

If the option argument contains both MACH_SEND_MSG and MACH_RCV_MSG, then mach_msg 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, mach_msg 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.

NOTES

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.

Major Concepts

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.

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.)

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.

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.

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.

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.

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.

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.

Port Rights

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.

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.

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.

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.

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.

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.

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.

In a sent message, the following mach_msg_type_name_t values denote port rights:

MACH_MSG_TYPE_MAKE_SEND
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.
MACH_MSG_TYPE_COPY_SEND
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.
MACH_MSG_TYPE_MOVE_SEND
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.
MACH_MSG_TYPE_MAKE_SEND_ONCE
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.
MACH_MSG_TYPE_MOVE_SEND_ONCE
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.
MACH_MSG_TYPE_MOVE_RECEIVE
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.

The following mach_msg_type_name_t values in a received message indicate that it carries port rights:

MACH_MSG_TYPE_PORT_SEND
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.
MACH_MSG_TYPE_PORT_SEND_ONCE
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.
MACH_MSG_TYPE_PORT_RECEIVE
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.

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.

Memory

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.

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.

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.

For each region, the sender has the choice of permitting the kernel to choose a transmission strategy or the choice of requiring physical copy:

MACH_MSG_VIRTUAL_COPY
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).

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.

MACH_MSG_PHYSICAL_COPY
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.

In a received message, this flag indicates that the kernel did transmit a physical copy.

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.

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.)

The copy option in the matching descriptor specifies the processing:

MACH_MSG_OVERWRITE
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.
MACH_MSG_ALLOCATE
This flag indicates that the region is to be dynamically allocated. No other descriptor values are relevant.

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).

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.

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.

Message Send

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.

The message carries with it the security ID of the sender, which the receiver can request in the message trailer.

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.

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.

MACH_SEND_TIMEOUT
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.
MACH_SEND_INTERRUPT
If specified, the mach_msg call will return MACH_SEND_INTERRUPTED if a software interrupt aborts the call. Otherwise, the send operation will be retried.
MACH_SEND_TRAILER
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 mach_msg still indicates the size of the message proper, not including this trailer.)

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.

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.

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.

Message Receive

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.

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.

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 mach_msg 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.

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.

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.

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.

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 mach_msg 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.

The following options modify MACH_RCV_MSG. If MACH_RCV_MSG is not also specified, they are ignored.

MACH_RCV_TIMEOUT
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.
MACH_RCV_NOTIFY
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.
MACH_RCV_INTERRUPT
If specified, the mach_msg call will return MACH_RCV_INTERRUPTED if a software interrupt aborts the call. Otherwise, the receive operation will be retried.
MACH_RCV_OVERWRITE
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 mach_msg_overwrite.
MACH_RCV_LARGE
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.
MACH_RCV_TRAILER_TYPE(value)
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.
MACH_RCV_TRAILER_ELEMENTS(value)
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.

The following trailer elements are supported:

MACH_RCV_TRAILER_SEQNO
Returns the sequence number of the message relative to its port. This value is of type mach_port_seqno_t.
MACH_RCV_TRAILER_SENDER
Returns the security ID of the task that sent the message. This value is of type security_id_t.

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.

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.

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.

Atomicity

The mach_msg 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.

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 mach_msg processes the port rights atomically, this succeeds. If msgh_remote_port were processed before msgh_local_port, then mach_msg would return MACH_SEND_INVALID_REPLY in this situation.

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, mach_msg can return either MACH_SEND_INVALID_DEST or MACH_SEND_INVALID_REPLY.

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.

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.

Implementation

mach_msg and mach_msg_overwrite are wrappers for a system call. They have the responsibility for repeating the interrupted system call.

CAUTIONS

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.

RETURN VALUES

The send operation can generate the following return codes. These return codes imply that the call did nothing:

MACH_SEND_MSG_TOO_SMALL
The specified send_size was smaller than the minimum size for a message.

MACH_SEND_NO_BUFFER
A resource shortage prevented the kernel from allocating a message buffer.

MACH_SEND_INVALID_DATA
The supplied message buffer was not readable.

MACH_SEND_INVALID_HEADER
The msgh_bits value was invalid.

MACH_SEND_INVALID_DEST
The msgh_remote_port value was invalid.

MACH_SEND_INVALID_NOTIFY
When using MACH_SEND_CANCEL, the notify argument did not denote a valid receive right.

MACH_SEND_INVALID_REPLY
The msgh_local_port value was invalid.

MACH_SEND_INVALID_TRAILER
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.

These return codes imply that some or all of the message was destroyed:

MACH_SEND_INVALID_MEMORY
The message body specified out-of-line data that was not readable.

MACH_SEND_INVALID_RIGHT
The message body specified a port right which the caller didn't possess.

MACH_SEND_INVALID_TYPE
A kernel processed descriptor was invalid.

MACH_SEND_MSG_TOO_SMALL
The last data item in the message ran over the end of the message.

These return codes imply that the message was returned to the caller with a pseudo-receive operation:

MACH_SEND_TIMED_OUT
The timeout interval expired.

MACH_SEND_INTERRUPTED
A software interrupt occurred.

This return code implies that the message was queued:

MACH_MSG_SUCCESS
The message was queued.

The receive operation can generate the following return codes. These return codes imply that the call did not de-queue a message:

MACH_RCV_INVALID_NAME
The specified receive_name was invalid.

MACH_RCV_IN_SET
The specified port was a member of a port set.

MACH_RCV_TIMED_OUT
The timeout interval expired.

MACH_RCV_INTERRUPTED
A software interrupt occurred.

MACH_RCV_PORT_DIED
The caller lost the rights specified by receive_name.

MACH_RCV_PORT_CHANGED
receive_name specified a receive right which was moved into a port set during the call.

MACH_RCV_TOO_LARGE
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.

MACH_RCV_SCATTER_SMALL
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.

MACH_RCV_INVALID_TRAILER
The trailer type desired, or the number of trailer elements desired, is not supported by the kernel.

These return codes imply that a message was de-queued and destroyed:

MACH_RCV_HEADER_ERROR
A resource shortage prevented the reception of the port rights in the message header.

MACH_RCV_INVALID_NOTIFY
When using MACH_RCV_NOTIFY, the notify argument did not denote a valid receive right.

MACH_RCV_INVALID_DATA
The specified message buffer was not writable.

MACH_RCV_TOO_LARGE
When not using MACH_RCV_LARGE, a message larger than receive_limit was de-queued and destroyed.

MACH_RCV_SCATTER_SMALL
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.

MACH_RCV_OVERWRITE_ERROR
A region specified by a receive overwrite descriptor (MACH_RCV_OVERWRITE) was not allocated or could not be written.

MACH_RCV_INVALID_TYPE
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.

MACH_RCV_LIMITS
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:

MACH_RCV_BODY_ERROR
A resource shortage prevented the reception of a port right or out-of- line memory region in the message body.

MACH_MSG_SUCCESS
A message was received.

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 mach_msg 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:

MACH_MSG_IPC_SPACE
There was no room in the task's IPC name space for another port name.

MACH_MSG_VM_SPACE
There was no room in the task's VM address space for an out-of-line memory region.

MACH_MSG_IPC_KERNEL
A kernel resource shortage prevented the reception of a port right.

MACH_MSG_VM_KERNEL
A kernel resource shortage prevented the reception of an out-of-line memory region.

RELATED INFORMATION

Functions: vm_allocate, vm_deallocate, vm_write, mach_port_request_notification,

Data Structures: mach_msg_header. \ No newline at end of file +

mach_msg

+
+

+System Trap / Function - Send and/or receive a message from the target port. +

SYNOPSIS

+
+mach_msg_return_t   mach_msg
+                    (mach_msg_header_t                msg,
+                     mach_msg_option_t             option,
+                     mach_msg_size_t            send_size,
+                     mach_msg_size_t        receive_limit,
+                     mach_port_t             receive_name,
+                     mach_msg_timeout_t           timeout,
+                     mach_port_t                   notify);
+
+mach_msg_return_t   mach_msg_overwrite
+                    (mach_msg_header_t*          send_msg,
+                     mach_msg_option_t             option,
+                     mach_msg_size_t            send_size,
+                     mach_msg_size_t        receive_limit,
+                     mach_port_t             receive_name,
+                     mach_msg_timeout_t           timeout,
+                     mach_port_t                   notify,
+                     mach_msg_header_t       *receive_msg,
+                     mach_msg_size_t     receive_msg_size);
+
+

PARAMETERS

+
+

+

msg +
+[pointer to in/out structure containing random and reply rights] A +message buffer used by mach_msg both for send and receive. This must +be naturally aligned. +

+

send_msg +
+[pointer to in structure containing random and reply rights] The mes- +sage buffer to be sent. This must be naturally aligned. +

+

option +
+[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. +

+

send_size +
+[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. +

+

receive_limit +
+[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. +

+

receive_name +
+[in random right] When receiving a message, specifies the port or port +set. Otherwise MACH_PORT_NULL should be supplied. +

+

timeout +
+[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. +

+

notify +
+[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. +

+

receive_msg +
+[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 (mach_msg), 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. +

+

receive_msg_size +
+[in scalar] When using the MACH_RCV_OVERWRITE option, specifies the +size (in bytes) of the receive "message" that is to be used by +mach_msg to indicate the disposition of received out-of-line regions. +
+

DESCRIPTION

+

+The mach_msg system call sends and receives Mach messages. Mach +messages contain data, which can include port rights and addresses of +large regions of memory. mach_msg 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 send_size 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. +

+If the option argument contains both MACH_SEND_MSG and MACH_RCV_MSG, +then mach_msg 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, mach_msg 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. +

NOTES

+

+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. +

Major Concepts

+

+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. +

+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.) +

+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. +

+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. +

+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. +

+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. +

+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. +

+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. +

Port Rights

+

+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. +

+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. +

+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. +

+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. +

+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. +

+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. +

+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. +

+In a sent message, the following mach_msg_type_name_t values denote +port rights: +

+
MACH_MSG_TYPE_MAKE_SEND +
+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. +
MACH_MSG_TYPE_COPY_SEND +
+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. +
MACH_MSG_TYPE_MOVE_SEND +
+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. +
MACH_MSG_TYPE_MAKE_SEND_ONCE +
+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. +
MACH_MSG_TYPE_MOVE_SEND_ONCE +
+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. +
MACH_MSG_TYPE_MOVE_RECEIVE +
+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. +
+

+The following mach_msg_type_name_t values in a received message +indicate that it carries port rights: +

+
MACH_MSG_TYPE_PORT_SEND +
+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. +
MACH_MSG_TYPE_PORT_SEND_ONCE +
+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. +
MACH_MSG_TYPE_PORT_RECEIVE +
+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. +
+

+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. +

Memory

+

+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. +

+ 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. +

+ 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. +

+For each region, the sender has the choice of permitting the kernel to +choose a transmission strategy or the choice of requiring physical +copy: +

+
MACH_MSG_VIRTUAL_COPY +
+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). +

+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. +

MACH_MSG_PHYSICAL_COPY +
+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. +

+In a received message, this flag indicates that the kernel did +transmit a physical copy. +

+

+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. +

+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.) +

+The copy option in the +matching descriptor specifies the processing: +

+
MACH_MSG_OVERWRITE +
+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. +
MACH_MSG_ALLOCATE +
+This flag indicates that the region is to be dynamically allocated. No +other descriptor values are relevant. +
+

+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). +

+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. +

+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. +

Message Send

+

+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. +

+The message carries with it the security ID of the sender, which the +receiver can request in the message trailer. +

+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. +

+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. +

+
MACH_SEND_TIMEOUT +
+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. +
MACH_SEND_INTERRUPT +
+If specified, the mach_msg call will return +MACH_SEND_INTERRUPTED if a software interrupt aborts the call. +Otherwise, the send operation will be retried. +
MACH_SEND_TRAILER +
+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 +mach_msg still indicates the size of the message proper, not including +this trailer.) +
+

+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. +

+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. +

+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. +

Message Receive

+

+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. +

+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. +

+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 mach_msg 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. +

+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. +

+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. +

+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. +

+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 mach_msg 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. +

+The following options modify MACH_RCV_MSG. If MACH_RCV_MSG is not also +specified, they are ignored. +

+
MACH_RCV_TIMEOUT +
+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. +
MACH_RCV_NOTIFY +
+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. +
MACH_RCV_INTERRUPT +
+If specified, the mach_msg call will return MACH_RCV_INTERRUPTED if a +software interrupt aborts the call. Otherwise, the receive operation +will be retried. +
MACH_RCV_OVERWRITE +
+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 mach_msg_overwrite. +
MACH_RCV_LARGE +
+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. +
MACH_RCV_TRAILER_TYPE(value) +
+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. +
MACH_RCV_TRAILER_ELEMENTS(value) +
+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. +
+

+ The following trailer elements are supported: +

+
MACH_RCV_TRAILER_SEQNO +
+Returns the sequence number of the message relative to its port. This +value is of type mach_port_seqno_t. +
MACH_RCV_TRAILER_SENDER +
+Returns the security ID of the task that sent the message. This value +is of type security_id_t. +
+

+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. +

+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. +

+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. +

Atomicity

+

+The mach_msg 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. +

+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 mach_msg processes the port rights atomically, this +succeeds. If msgh_remote_port were processed before msgh_local_port, +then mach_msg would return MACH_SEND_INVALID_REPLY in this situation. +

+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, mach_msg can +return either MACH_SEND_INVALID_DEST or MACH_SEND_INVALID_REPLY. +

+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. +

+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. +

Implementation

+

+mach_msg and mach_msg_overwrite are wrappers for a system call. They +have the responsibility for repeating the interrupted system call. +

CAUTIONS

+

+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. +

RETURN VALUES

+

+The send operation can generate the following return codes. These +return codes imply that the call did nothing: +

+

+

MACH_SEND_MSG_TOO_SMALL +
+The specified send_size was smaller than the minimum size for a +message. +

+

MACH_SEND_NO_BUFFER +
+A resource shortage prevented the kernel from allocating a message +buffer. +

+

MACH_SEND_INVALID_DATA +
+The supplied message buffer was not readable. +

+

MACH_SEND_INVALID_HEADER +
+The msgh_bits value was invalid. +

+

MACH_SEND_INVALID_DEST +
+The msgh_remote_port value was invalid. +

+

MACH_SEND_INVALID_NOTIFY +
+When using MACH_SEND_CANCEL, the notify argument did not +denote a valid receive right. +

+

MACH_SEND_INVALID_REPLY +
+The msgh_local_port value was invalid. +

+

MACH_SEND_INVALID_TRAILER +
+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. +
+

+These return codes imply that some or all of the message was destroyed: +

+

+

MACH_SEND_INVALID_MEMORY +
+The message body specified out-of-line data that was not readable. +

+

MACH_SEND_INVALID_RIGHT +
+The message body specified a port right which the caller didn't possess. +

+

MACH_SEND_INVALID_TYPE +
+A kernel processed descriptor was invalid. +

+

MACH_SEND_MSG_TOO_SMALL +
+The last data item in the message ran over the end of the message. +
+

+These return codes imply that the message was returned to the caller with a +pseudo-receive operation: +

+

+

MACH_SEND_TIMED_OUT +
+The timeout interval expired. +

+

MACH_SEND_INTERRUPTED +
+A software interrupt occurred. +
+

+This return code implies that the message was queued: +

+

+

MACH_MSG_SUCCESS +
+The message was queued. +
+

+The receive operation can generate the following return codes. These return +codes imply that the call did not de-queue a message: +

+

+

MACH_RCV_INVALID_NAME +
+The specified receive_name was invalid. +

+

MACH_RCV_IN_SET +
+The specified port was a member of a port set. +

+

MACH_RCV_TIMED_OUT +
+The timeout interval expired. +

+

MACH_RCV_INTERRUPTED +
+A software interrupt occurred. +

+

MACH_RCV_PORT_DIED +
+The caller lost the rights specified by receive_name. +

+

MACH_RCV_PORT_CHANGED +
+receive_name specified a receive right which was moved into a port set +during the call. +

+

MACH_RCV_TOO_LARGE +
+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. +

+

MACH_RCV_SCATTER_SMALL +
+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. +

+

MACH_RCV_INVALID_TRAILER +
+The trailer type desired, or the number of trailer elements desired, is +not supported by the kernel. +
+

+These return codes imply that a message was de-queued and destroyed: +

+

+

MACH_RCV_HEADER_ERROR +
+A resource shortage prevented the reception of the port rights in the +message header. +

+

MACH_RCV_INVALID_NOTIFY +
+When using MACH_RCV_NOTIFY, the notify argument did not denote a +valid receive right. +

+

MACH_RCV_INVALID_DATA +
+The specified message buffer was not writable. +

+

MACH_RCV_TOO_LARGE +
+When not using MACH_RCV_LARGE, a message larger than +receive_limit was de-queued and destroyed. +

+

MACH_RCV_SCATTER_SMALL +
+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. +

+

MACH_RCV_OVERWRITE_ERROR +
+A region specified by a receive overwrite descriptor +(MACH_RCV_OVERWRITE) was not allocated or could not be written. +

+

MACH_RCV_INVALID_TYPE +
+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. +

+

MACH_RCV_LIMITS +
+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: +

+

MACH_RCV_BODY_ERROR +
+A resource shortage prevented the reception of a port right or out-of- +line memory region in the message body. +

+

MACH_MSG_SUCCESS +
+A message was received. +
+

+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 mach_msg 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: +

+

+

MACH_MSG_IPC_SPACE +
+There was no room in the task's IPC name space for another port name. +

+

MACH_MSG_VM_SPACE +
+There was no room in the task's VM address space for an out-of-line +memory region. +

+

MACH_MSG_IPC_KERNEL +
+A kernel resource shortage prevented the reception of a port right. +

+

MACH_MSG_VM_KERNEL +
+A kernel resource shortage prevented the reception of an out-of-line +memory region. +
+

RELATED INFORMATION

+

+Functions: +vm_allocate, +vm_deallocate, +vm_write, +mach_port_request_notification, +

+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 @@ -

mach_msg_descriptor

Structure - Specifies operations that must be performed on a given IPC message element.

SYNOPSIS

typedef struct
{
       void*                             pad1;
       mach_msg_size_t                   pad2;
       unsigned int                      pad3 : 24;
       mach_msg_descriptor_type_t        type : 8;
} mach_msg_type_descriptor_t;

typedef struct
{
       mach_port_t                       name;
       mach_msg_size_t                   pad1;
       unsigned int                      pad2 : 16;
       mach_msg_type_name_t       disposition : 8;
       mach_msg_descriptor_type_t        type : 8;
} mach_msg_port_descriptor_t;

typedef struct
{
       void*                          address;
       mach_msg_size_t                   size;
       boolean_t                   deallocate : 8;
       mach_msg_copy_options_t           copy : 8;
       unsigned int                      pad1 : 8;
       mach_msg_descriptor_type_t        type : 8;
} mach_msg_ool_descriptor_t;

typedef struct
{
       void*                           address;
       mach_msg_size_t                   count;
       boolean_t                    deallocate : 8;
       mach_msg_copy_options_t            copy : 8;
       mach_msg_type_name_t        disposition : 8;
       mach_msg_descriptor_type_t         type : 8;
} mach_msg_ool_ports_descriptor_t;

typedef union
{
       mach_msg_port_descriptor_t             port;
       mach_msg_ool_descriptor_t       out_of_line;
       mach_msg_ool_ports_descriptor_t   ool_ports;
       mach_msg_type_descriptor_t             type;
} mach_msg_descriptor_t;

FIELDS

name
For single port descriptors, the name of the port whose right is being sent.

disposition
For single port or out-of-line port array descriptors, the IPC processing to be done for the rights for the named ports.

address
For out-of-line data or port array descriptors, the address of the out-of-line data or port (name) array.

size
For out-of-line data descriptors, the size of the out-of-line region, in bytes.

deallocate
For out-of-line data descriptors, true if the set of pages containing the array should be de-allocated when the message is sent.

copy
For out-of-line descriptors, a description of the method by which the data should be copied.

count
For out-of-line port array descriptors, the number of port names in the array.

type
For any type of descriptor, the type of descriptor.

port
A descriptor that describes a single port right.

out_of_line
A descriptor that describes an out-of-line data array.

ool_ports
A descriptor that describes an out-of-line port array.

DESCRIPTION

A mach_msg_descriptor structure describes the processing to be performed for an element of kernel-processed data in a Mach message.

RELATED INFORMATION

Functions: mach_msg.

Data Structures: mach_msg_header. \ No newline at end of file +

mach_msg_descriptor

+
+

+Structure - Specifies operations that must be performed on a given IPC message element. +

SYNOPSIS

+
+typedef struct
+{
+       void*                             pad1;
+       mach_msg_size_t                   pad2;
+       unsigned int                      pad3 : 24;
+       mach_msg_descriptor_type_t        type : 8;
+} mach_msg_type_descriptor_t;
+
+typedef struct
+{
+       mach_port_t                       name;
+       mach_msg_size_t                   pad1;
+       unsigned int                      pad2 : 16;
+       mach_msg_type_name_t       disposition : 8;
+       mach_msg_descriptor_type_t        type : 8;
+} mach_msg_port_descriptor_t;
+
+typedef struct
+{
+       void*                          address;
+       mach_msg_size_t                   size;
+       boolean_t                   deallocate : 8;
+       mach_msg_copy_options_t           copy : 8;
+       unsigned int                      pad1 : 8;
+       mach_msg_descriptor_type_t        type : 8;
+} mach_msg_ool_descriptor_t;
+
+typedef struct
+{
+       void*                           address;
+       mach_msg_size_t                   count;
+       boolean_t                    deallocate : 8;
+       mach_msg_copy_options_t            copy : 8;
+       mach_msg_type_name_t        disposition : 8;
+       mach_msg_descriptor_type_t         type : 8;
+} mach_msg_ool_ports_descriptor_t;
+
+typedef union
+{
+       mach_msg_port_descriptor_t             port;
+       mach_msg_ool_descriptor_t       out_of_line;
+       mach_msg_ool_ports_descriptor_t   ool_ports;
+       mach_msg_type_descriptor_t             type;
+} mach_msg_descriptor_t;
+
+

FIELDS

+
+
name +
+For single port descriptors, the name of the port whose right is being +sent. +

+

disposition +
+For single port or out-of-line port array descriptors, the IPC processing +to be done for the rights for the named ports. +

+

address +
+For out-of-line data or port array descriptors, the address of the +out-of-line data or port (name) array. +

+

size +
+For out-of-line data descriptors, the size of the out-of-line region, in +bytes. +

+

deallocate +
+For out-of-line data descriptors, true if the set of pages containing the +array should be de-allocated when the message is sent. +

+

copy +
+For out-of-line descriptors, a description of the method by which the +data should be copied. +

+

count +
+For out-of-line port array descriptors, the number of port names in the +array. +

+

type +
+For any type of descriptor, the type of descriptor. +

+

port +
+A descriptor that describes a single port right. +

+

out_of_line +
+A descriptor that describes an out-of-line data array. +

+

ool_ports +
+A descriptor that describes an out-of-line port array. +
+

DESCRIPTION

+

+A mach_msg_descriptor structure describes the processing +to be performed +for an element of kernel-processed data in a Mach message. +

RELATED INFORMATION

+

+Functions: +mach_msg. +

+Data Structures: +mach_msg_header. 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 @@ -

mach_msg_header

Structure - Specifies the content of an IPC message header.

SYNOPSIS

typedef struct
{
       mach_msg_bits_t                     msgh_bits;
       mach_msg_size_t                     msgh_size;
       mach_port_t                  msgh_remote_port;
       mach_port_t                   msgh_local_port;
       mach_msg_size_t                 msgh_reserved;
       mach_msg_id_t                         msgh_id;
} mach_msg_header_t;

typedef struct
{
       mach_msg_size_t         msgh_descriptor_count;
} mach_msg_body_t;

typedef struct
{
       mach_msg_trailer_type_t     msgh_trailer_type;
       mach_msg_trailer_size_t     msgh_trailer_size;
} mach_msg_trailer_t;

typedef struct
{
       mach_msg_trailer_type_t     msgh_trailer_type;
       mach_msg_trailer_size_t     msgh_trailer_size;
       mach_port_seqno_t                  msgh_seqno;
} mach_msg_seqno_trailer_t;

typedef struct
{
       mach_msg_trailer_type_t    msgh_trailer_type;
       mach_msg_trailer_size_t    msgh_trailer_size;
       mach_port_seqno_t                 msgh_seqno;
       security_token_t                 msgh_sender;
} mach_msg_security_trailer_t;

typedef struct
{
       mach_msg_trailer_type_t    msgh_trailer_type;
       mach_msg_trailer_size_t    msgh_trailer_size;
       mach_port_seqno_t                 msgh_seqno;
       security_token_t                  msgh_sender;
       unsigned int                 dipc_sender_kmsg;
} mach_msg_dipc_trailer_t;

FIELDS

msgh_bits
This field specifies the following properties of the message:

MACH_MSGH_BITS_REMOTE_MASK
Encodes mach_msg_type_name_t values that specify the port rights in the msgh_remote_port field. The value must specify a send or send-once right for the destination of the message.

MACH_MSGH_BITS_LOCAL_MASK
Encodes mach_msg_type_name_t values that specify the port rights in the msgh_local_port field. If the value doesn't specify a send or send-once right for the message's reply port, it must be zero and msgh_local_port must be MACH_PORT_NULL.

MACH_MSGH_BITS_COMPLEX
The complex bit must be specified if the message body contains additional port rights or out-of-line memory regions.

MACH_MSGH_BITS_REMOTE(bits)
This macro returns the appropriate mach_msg_type_name_t values, given a msgh_bits value.

MACH_MSGH_BITS_LOCAL(bits)
This macro returns the appropriate mach_msg_type_name_t values, given a msgh_bits value.

MACH_MSGH_BITS(remote, local)
This macro constructs a value for msgh_bits, given two mach_msg_type_name_t values.

msgh_size
This field is ignored on send (the size to send is specified by the send_size parameter to mach_msg); 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.

msgh_remote_port
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 msgh_local_port.

msgh_local_port
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, MACH_PORT_NULL, or MACH_PORT_DEAD. When received, this field is swapped with msgh_remote_port.

msgh_id
Not set or read by the mach_msg call. The conventional meaning is to convey an operation or function ID.

msgh_descriptor_count
The number of descriptors of kernel processed data (port rights and out-of-line data).

msgh_trailer_type
An identifier of the trailer version. Different values indicate not necessarily compatible trailer formats. The current (and only) trailer format is MACH_MSG_TRAILER_FORMAT_0. There is currently only one attribute defined within this trailer type: the sender's identity.

msgh_trailer_size
The length, in bytes, of the message trailer, including the trailer type and length fields.

msgh_seqno
The sequence number of this message relative to the port from which it is received.

msgh_sender
The security ID of the sender of the message.

DESCRIPTION

The mach_msg_header 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.

If the MACH_MSGH_BITS_COMPLEX flag in the msgh_bits field is not set, then this is a simple message described by mach_msg_header_t. In this case, the header is immediately followed by untyped data.

If the complex flag is set, then this is a "complex" message consisting of a mach_msg_header_t structure followed by a mach_msg_body_t 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.

Following the header (and any kernel processed descriptors), at natural alignment can be additional (un-typed) data, up to the size of the message (msgh_size). This extra data typically carries information used to decode the data stream and out-of-line data.

At the next natural boundary following the message data is the message trailer (mach_msg_trailer_t). This structure indicates the type and length of the trailer. If the length is greater than sizeof (mach_msg_trailer_t), additional fields follow providing kernel-generated message attributes.

RELATED INFORMATION

Functions: mach_msg.

Data Structures: mach_msg_descriptor. \ No newline at end of file +

mach_msg_header

+
+

+Structure - Specifies the content of an IPC message header. +

SYNOPSIS

+
+typedef struct
+{
+       mach_msg_bits_t                     msgh_bits;
+       mach_msg_size_t                     msgh_size;
+       mach_port_t                  msgh_remote_port;
+       mach_port_t                   msgh_local_port;
+       mach_msg_size_t                 msgh_reserved;
+       mach_msg_id_t                         msgh_id;
+} mach_msg_header_t;
+
+typedef struct
+{
+       mach_msg_size_t         msgh_descriptor_count;
+} mach_msg_body_t;
+
+typedef struct
+{
+       mach_msg_trailer_type_t     msgh_trailer_type;
+       mach_msg_trailer_size_t     msgh_trailer_size;
+} mach_msg_trailer_t;
+
+typedef struct
+{
+       mach_msg_trailer_type_t     msgh_trailer_type;
+       mach_msg_trailer_size_t     msgh_trailer_size;
+       mach_port_seqno_t                  msgh_seqno;
+} mach_msg_seqno_trailer_t;
+
+typedef struct
+{
+       mach_msg_trailer_type_t    msgh_trailer_type;
+       mach_msg_trailer_size_t    msgh_trailer_size;
+       mach_port_seqno_t                 msgh_seqno;
+       security_token_t                 msgh_sender;
+} mach_msg_security_trailer_t;
+
+typedef struct
+{
+       mach_msg_trailer_type_t    msgh_trailer_type;
+       mach_msg_trailer_size_t    msgh_trailer_size;
+       mach_port_seqno_t                 msgh_seqno;
+       security_token_t                  msgh_sender;
+       unsigned int                 dipc_sender_kmsg;
+} mach_msg_dipc_trailer_t;
+
+

FIELDS

+
+
msgh_bits +
+This field specifies the following properties of the message: +
+

+

MACH_MSGH_BITS_REMOTE_MASK +
+Encodes mach_msg_type_name_t values that specify the port +rights in the msgh_remote_port field. The value must specify +a send or send-once right for the destination of the message. +

+

MACH_MSGH_BITS_LOCAL_MASK +
+Encodes mach_msg_type_name_t values that specify the port +rights in the msgh_local_port field. If the value doesn't +specify a send or send-once right for the message's reply port, it +must be zero and msgh_local_port must be MACH_PORT_NULL. +

+

MACH_MSGH_BITS_COMPLEX +
+The complex bit must be specified if the message body +contains additional port rights or out-of-line memory regions. +

+

MACH_MSGH_BITS_REMOTE(bits) +
+This macro returns the appropriate mach_msg_type_name_t +values, given a msgh_bits value. +

+

MACH_MSGH_BITS_LOCAL(bits) +
+This macro returns the appropriate mach_msg_type_name_t +values, given a msgh_bits value. +

+

MACH_MSGH_BITS(remote, local) +
+This macro constructs a value for msgh_bits, given two +mach_msg_type_name_t values. +
+

+

msgh_size +
+This field is ignored on send (the size to send is specified by the +send_size parameter to mach_msg); 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. +

+

msgh_remote_port +
+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 msgh_local_port. +

+

msgh_local_port +
+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, MACH_PORT_NULL, or +MACH_PORT_DEAD. When received, this field is swapped with +msgh_remote_port. +

+

msgh_id +
+Not set or read by the mach_msg call. The conventional meaning is to +convey an operation or function ID. +

+

msgh_descriptor_count +
+The number of descriptors of kernel processed data (port rights and +out-of-line data). +

+

msgh_trailer_type +
+An identifier of the trailer version. Different values indicate not +necessarily compatible trailer formats. The current (and only) trailer format +is MACH_MSG_TRAILER_FORMAT_0. There is currently only one +attribute defined within this trailer type: the sender's identity. +

+

msgh_trailer_size +
+The length, in bytes, of the message trailer, including the trailer type +and length fields. +

+

msgh_seqno +
+The sequence number of this message relative to the port from which it +is received. +

+

msgh_sender +
+The security ID of the sender of the message. +
+

DESCRIPTION

+

+The mach_msg_header 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. +

+If the MACH_MSGH_BITS_COMPLEX flag in the msgh_bits field is not set, +then this is a simple message described by mach_msg_header_t. +In this case, the header is immediately followed by untyped data. +

+If the complex flag is set, then this is a "complex" message consisting of a +mach_msg_header_t structure followed by a mach_msg_body_t 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. +

+Following the header (and any kernel processed descriptors), at natural +alignment can be additional (un-typed) data, up to the size of the message +(msgh_size). This extra data typically carries information +used to decode the data stream and out-of-line data. +

+At the next natural boundary following the message data is the message trailer +(mach_msg_trailer_t). This structure indicates the type and length of the +trailer. If the length is greater than sizeof (mach_msg_trailer_t), +additional fields +follow providing kernel-generated message attributes. +

RELATED INFORMATION

+

+Functions: +mach_msg. +

+Data Structures: +mach_msg_descriptor. + 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 @@ -

mach_port_allocate

Function - Create caller-specified type of port right.

SYNOPSIS

kern_return_t   mach_port_allocate
                (ipc_space_t                               task,
                 mach_port_right_t                        right,
                 mach_port_name_t                         *name);

PARAMETERS

task
[in task send right] The task acquiring the port right.

right
[in scalar] The kind of entity to be created. This is one of the following:

MACH_PORT_RIGHT_RECEIVE
mach_port_allocate 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. name denotes the receive right for the new port. task does not hold send rights for the new port, only the receive right. mach_port_insert_right and mach_port_extract_right can be used to convert the receive right into a combined send/receive right.

MACH_PORT_RIGHT_PORT_SET
mach_port_allocate creates a port set. The new port set has no members.

MACH_PORT_RIGHT_DEAD_NAME
mach_port_allocate creates a dead name. The new dead name has one user reference.

name
[out scalar] The task's name for the port right. This can be any name that wasn't in use.

DESCRIPTION

The mach_port_allocate function creates a new right in the specified task. The new right's name is returned in name.

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 mach_port_allocate_full interface to allocate ports that support the full set of Mach port semantics.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_NO_SPACE
There was no room in task's IPC name space for another right.

RELATED INFORMATION

Functions: mach_port_allocate_name, mach_port_deallocate, mach_port_insert_right, mach_port_extract_right. \ No newline at end of file +

mach_port_allocate

+
+

+Function - Create caller-specified type of port right. +

SYNOPSIS

+
+kern_return_t   mach_port_allocate
+                (ipc_space_t                               task,
+                 mach_port_right_t                        right,
+                 mach_port_name_t                         *name);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task acquiring the port right. +

+

right +
+[in scalar] +The kind of entity to be created. This is one of the following: +
+

+

MACH_PORT_RIGHT_RECEIVE +
+mach_port_allocate 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. name denotes the +receive right for the new port. +task does not hold send rights for the new port, only the +receive right. mach_port_insert_right and +mach_port_extract_right can be used to convert the receive right into a +combined send/receive right. +

+

MACH_PORT_RIGHT_PORT_SET +
+mach_port_allocate creates a port set. The new port set has +no members. +

+

MACH_PORT_RIGHT_DEAD_NAME +
+mach_port_allocate creates a dead name. The new dead +name has one user reference. +
+

+

name +
+[out scalar] +The task's name for the port right. This can be any name +that wasn't in use. +
+

DESCRIPTION

+

+The mach_port_allocate function creates a new right +in the specified task. The new right's name is returned in name. +

+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 mach_port_allocate_full +interface to allocate ports that support the full set of Mach port semantics. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_NO_SPACE +
+There was no room in task's IPC name space for another right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate_name, +mach_port_deallocate, +mach_port_insert_right, +mach_port_extract_right. 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 @@ -

mach_port_allocate_full

Function - Create a port right with full Mach port semantics.

SYNOPSIS

kern_return_t   mach_port_allocate_full
                (ipc_space_t                               task,
                 mach_port_right_t                        right,
                 subsystem_t                          subsystem,
                 mach_port_qos_t                            qos,
                 task                                      name);

PARAMETERS

task
[in task send right] The task acquiring the port right.

right
[in scalar] The kind of entity to be created. This is one of the following:

MACH_PORT_RIGHT_RECEIVE
mach_port_allocate_full 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 name 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 mach_port_insert_right and mach_port_extract_right interfaces can be used to convert the receive right to a combined send/receive right.

MACH_PORT_RIGHT_PORT_SET
mach_port_allocate_full creates a port set. The new port set has no members.

MACH_PORT_RIGHT_DEAD_NAME
mach_port_allocate_full creates a dead name. The new dead name has one user reference.

subsystem
[in scalar] The port right naming the subsystem the newly created port is to be associated with.

qos
[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.
name
[out scalar] The task's name for the port right. This can be any name that wasn't in use.

DESCRIPTION

The mach_port_allocate_full function creates a new right in the specified task. The new right's name is returned via the name parameter. The new port supports the full set of Mach port semantics (i.e. no_more_senders detection will work, if requested).

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_NO_SPACE
There was no room in task's IPC name space for another right.

RELATED INFORMATION

Functions: mach_port_allocate, mach_port_allocate_qos, mach_port_allocate_name, mach_port_deallocate, mach_port_insert_right, mach_port_extract_right.

Structures: mach_port_qos. \ No newline at end of file +

mach_port_allocate_full

+
+

+Function - Create a port right with full Mach port semantics. +

SYNOPSIS

+
+kern_return_t   mach_port_allocate_full
+                (ipc_space_t                               task,
+                 mach_port_right_t                        right,
+                 subsystem_t                          subsystem,
+                 mach_port_qos_t                            qos,
+                 task                                      name);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] The task acquiring the port right. +

+

right +
+[in scalar] The kind of entity to be created. This is one of the following: +
+

+

MACH_PORT_RIGHT_RECEIVE +
+mach_port_allocate_full 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 name 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 mach_port_insert_right +and mach_port_extract_right interfaces can be used +to convert the receive right to a combined send/receive right. +

+

MACH_PORT_RIGHT_PORT_SET +
+mach_port_allocate_full creates a port set. The new port set +has no members. +

+

MACH_PORT_RIGHT_DEAD_NAME +
+mach_port_allocate_full creates a dead name. The new dead +name has one user reference. +
+

+

subsystem +
+[in scalar] The port right naming the subsystem the newly created port +is to be associated with. +

+

+

qos +
+[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. +
name +
+[out scalar] The task's name for the port right. This can be any name +that wasn't in use. +
+

DESCRIPTION

+

+The mach_port_allocate_full function creates a new right in the +specified task. The new right's name is returned via the name parameter. +The new port supports the full set of Mach port semantics (i.e. no_more_senders +detection will work, if requested). +

NOTES

+

+This interface is machine word length specific because of the port +name parameter. +

RETURN VALUES

+
+

+

KERN_NO_SPACE +
+There was no room in task's IPC name space for another right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate, +mach_port_allocate_qos, +mach_port_allocate_name, +mach_port_deallocate, +mach_port_insert_right, +mach_port_extract_right. +

+Structures: +mach_port_qos. 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 @@ -

mach_port_allocate_name

Function - Create a port right with the caller-specified name.

SYNOPSIS

kern_return_t   mach_port_allocate_name
                (ipc_space_t                               task,
                 mach_port_right_t                        right,
                 mach_port_name_t                          name);

PARAMETERS

task
[in task send right] The task acquiring the port right.

right
[in scalar] The kind of entity to be created. This is one of the following:

MACH_PORT_RIGHT_RECEIVE
mach_port_allocate_name 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. name denotes the receive right for the new port. task does not hold send rights for the new port, only the receive right. mach_port_insert_right and mach_port_extract_right can be used to convert the receive right into a combined send/receive right.

MACH_PORT_RIGHT_PORT_SET
mach_port_allocate_name creates a port set. The new port set has no members.

MACH_PORT_RIGHT_DEAD_NAME
mach_port_allocate_name creates a dead name. The new dead name has one user reference.

name
[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 MACH_PORT_NULL and MACH_PORT_DEAD.

DESCRIPTION

The mach_port_allocate_name function creates a new right in the specified task, with a specified name for the new right.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_NAME_EXISTS
name was already in use for a port right.

RELATED INFORMATION

Functions: mach_port_allocate, mach_port_deallocate, mach_port_insert_right, mach_port_extract_right. \ No newline at end of file +

mach_port_allocate_name

+
+

+Function - Create a port right with the caller-specified name. +

SYNOPSIS

+
+kern_return_t   mach_port_allocate_name
+                (ipc_space_t                               task,
+                 mach_port_right_t                        right,
+                 mach_port_name_t                          name);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task acquiring the port right. +

+

right +
+[in scalar] +The kind of entity to be created. This is one of the following: +
+

+

MACH_PORT_RIGHT_RECEIVE +
+mach_port_allocate_name 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. +name denotes the receive right for the new port. +task does not hold send rights for the new port, only the +receive right. mach_port_insert_right and +mach_port_extract_right can be used to convert the receive right into a +combined send/receive right. +

+

MACH_PORT_RIGHT_PORT_SET +
+mach_port_allocate_name creates a port set. The new port +set has no members. +

+

MACH_PORT_RIGHT_DEAD_NAME +
+mach_port_allocate_name creates a dead name. The new +dead name has one user reference. +
+

+

name +
+[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 +MACH_PORT_NULL and MACH_PORT_DEAD. +
+

DESCRIPTION

+

+The mach_port_allocate_name function creates a new +right in the specified +task, with a specified name for the new right. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_NAME_EXISTS +
+name was already in use for a port right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate, +mach_port_deallocate, +mach_port_insert_right, +mach_port_extract_right. 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 @@ -

mach_port_allocate_qos

Function - Allocate a port with specified "quality of service."

SYNOPSIS

kern_return_t	mach_port_allocate_qos
		(ipc_space_t	task,
		mach_port_right_t	right,
		mach_port_qos_t	qos,
		mach_port_name_t*	name);

PARAMETERS

task
[in task send right] The task acquiring the port right to the allocated port.
right
[in scalar] The type of port right to map to the allocated port.
qos
[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.
name
[in/out scalar] The name of the installed port right, either specified by the caller or chosen by the system.

DESCRIPTION

The mach_port_allocate_qos 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).

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_NO_SPACE
There was no room in task's IPC name space for another right.
KERN_INVALID_VALUE
The type of right specified by right is either invalid or conflicts with the requested "quality of service" as specified via qos.

RELATED INFORMATION

Functions: mach_port_allocate, mach_port_allocate_full, mach_port_allocate_name, mach_port_deallocate, mach_port_insert_right, mach_port_extract_right.

Structures: mach_port_qos. \ No newline at end of file +

mach_port_allocate_qos

+
+

+Function - Allocate a port with specified "quality of service." +

SYNOPSIS

+
+kern_return_t	mach_port_allocate_qos
+		(ipc_space_t	task,
+		mach_port_right_t	right,
+		mach_port_qos_t	qos,
+		mach_port_name_t*	name);
+
+

PARAMETERS

+
+
task +
+[in task send right] The task acquiring the port right to the allocated port. +
right +
+[in scalar] The type of port right to map to the allocated port. +
qos +
+[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. +
name +
+[in/out scalar] The name of the installed port right, either specified by the + caller or chosen by the system. +
+

DESCRIPTION

+

+The mach_port_allocate_qos 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). +

NOTES

+

+This interface is machine word length specific because of the port +name parameter. +

RETURN VALUES

+
+
KERN_NO_SPACE +
+There was no room in task's IPC name space for another right. +
KERN_INVALID_VALUE +
+The type of right specified by right is either invalid or conflicts +with the requested "quality of service" as specified via qos. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate, +mach_port_allocate_full, +mach_port_allocate_name, +mach_port_deallocate, +mach_port_insert_right, +mach_port_extract_right. +

+Structures: +mach_port_qos. \ 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 @@ -

mach_port_deallocate

Function - Decrement the target port right's user reference count.

SYNOPSIS

kern_return_t   mach_port_deallocate
                (ipc_space_t                               task,
                 mach_port_name_t                          name);

PARAMETERS

task
[in task send right] The task holding the right.

name
[in scalar] The task's name for the right.

DESCRIPTION

The mach_port_deallocate function releases a user reference for a right. It is an alternate form of mach_port_mod_refs 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.

If name 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 name does not denote an element in the port name space, the function returns success.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_RIGHT
The name parameter denoted an invalid right.

RELATED INFORMATION

Functions: mach_port_allocate, mach_port_allocate_name, mach_port_mod_refs. \ No newline at end of file +

mach_port_deallocate

+
+

+Function - Decrement the target port right's user reference count. +

SYNOPSIS

+
+kern_return_t   mach_port_deallocate
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task holding the right. +

+

name +
+[in scalar] +The task's name for the right. +
+

DESCRIPTION

+

+The mach_port_deallocate function releases a user reference +for a right. It is +an alternate form of mach_port_mod_refs 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. +

+If name 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 name does not denote an element in the port name space, the +function returns +success. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_RIGHT +
+The name parameter denoted an invalid right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate, +mach_port_allocate_name, +mach_port_mod_refs. 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 @@ -

mach_port_destroy

Function - Deallocate all port rights associated with specified name.

SYNOPSIS

kern_return_t   mach_port_destroy
                (ipc_space_t                               task,
                 mach_port_name_t                          name);

PARAMETERS

task
[in task send right] The task holding the right.

name
[in scalar] The task's name for the right.

DESCRIPTION

The mach_port_destroy function de-allocates all rights denoted by a name. The name becomes immediately available for reuse.

For most purposes, mach_port_mod_refs and mach_port_deallocate are preferable.

If name denotes a port set, then all members of the port set are implicitly removed from the port set.

If name 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.

If name denotes a send-once right, then the destruction of the send-once right produces a send-once notification for the port.

If name 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).

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
The name parameter did not denote a right.

RELATED INFORMATION

Functions: mach_port_allocate, mach_port_allocate_name, mach_port_mod_refs, mach_port_deallocate, mach_port_request_notification. \ No newline at end of file +

mach_port_destroy

+
+

+Function - Deallocate all port rights associated with specified name. +

SYNOPSIS

+
+kern_return_t   mach_port_destroy
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task holding the right. +

+

name +
+[in scalar] +The task's name for the right. +
+

DESCRIPTION

+

+The mach_port_destroy function de-allocates all rights +denoted by a name. +The name becomes immediately available for reuse. +

+For most purposes, +mach_port_mod_refs and mach_port_deallocate are +preferable. +

+If name denotes a port set, then all members of the port set are implicitly +removed from the port set. +

+If name 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. +

+If name denotes a send-once right, then +the destruction of the send-once right +produces a send-once notification for the port. +

+If name 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). +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+The name parameter did not denote a right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate, +mach_port_allocate_name, +mach_port_mod_refs, +mach_port_deallocate, +mach_port_request_notification. 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 @@ - mach_port_insert_member.html

mach_port_extract_member

Function - Extract the specified receive right from the specified port set.

SYNOPSIS

kern_return_t   mach_port_extract_member
                (ipc_space_t                               task,
                 mach_port_name_t                        member,
                 mach_port_name_t                         set);

PARAMETERS

task
[in task send right] The task holding the port set and receive right.
member
[in scalar] The task's name for the receive right.
set
[in scalar] The task's name for the port set.

DESCRIPTION

The mach_port_extract_member 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.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
member or set did not denote a right.
KERN_INVALID_RIGHT
member denoted a right, but not a receive right, or set denoted a right, but not a port set.
KERN_NOT_IN_SET
member was not in set.

RELATED INFORMATION

Functions: mach_port_extract_member, mach_port_move_member, mach_port_get_set_status, mach_port_get_attributes. \ No newline at end of file + + + + + + mach_port_insert_member.html + + + +

+mach_port_extract_member

+ +
+

Function - Extract the specified receive right from the specified +port set. +

+SYNOPSIS

+ +
kern_return_t   mach_port_extract_member
+                (ipc_space_t                               task,
+                 mach_port_name_t                        member,
+                 mach_port_name_t                         set);
+ +

+PARAMETERS

+ +
+
+task
+ +
+[in task send right] The task holding the port set and receive right.
+ +
+member
+ +
+[in scalar] The task's name for the receive right.
+ +
+set
+ +
+[in scalar] The task's name for the port set.
+
+ +

+DESCRIPTION

+The mach_port_extract_member 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. +

+NOTES

+This interface is machine word length specific because of the port name +parameter. +

+RETURN VALUES

+ +
+
+KERN_INVALID_NAME
+ +
+member or set did not denote a right.
+ +
+KERN_INVALID_RIGHT
+ +
+member denoted a right, but not a receive right, or set denoted +a right, but not a port set.
+ +
+KERN_NOT_IN_SET
+ +
+member was not in set.
+
+ +

+RELATED INFORMATION

+Functions: +mach_port_extract_member, +mach_port_move_member, +mach_port_get_set_status, +mach_port_get_attributes. + + 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 @@ -

mach_port_extract_right

Function - Remove the specified right from the target task and return it to the caller.

SYNOPSIS

kern_return_t   mach_port_extract_right
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_msg_type_name_t              desired_type,
                 mach_port_poly_t                        *right,
                 mach_msg_type_name_             *acquired_type);

PARAMETERS

task
[in task send right] The task holding the port right.

name
[in scalar] The task's name for the port right.

desired_type
[in scalar] IPC type, specifying how the right should be extracted.

right
[out random right] The extracted right.

acquired_type
[out scalar] The type of the extracted right.

DESCRIPTION

The mach_port_extract_right function extracts a port right from the target task and returns it to the caller as if the task sent the right voluntarily, using desired_type as the disposition for the right. See mach_msg.

The returned value of acquired_type will be MACH_MSG_TYPE_PORT_SEND if a send right is extracted, MACH_MSG_TYPE_PORT_RECEIVE if a receive right is extracted, and MACH_MSG_TYPE_PORT_SEND_ONCE if a send-once right is extracted.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
name did not denote a right.

KERN_INVALID_RIGHT
name denoted an invalid right.

RELATED INFORMATION

Functions: mach_port_insert_right, mach_msg. \ No newline at end of file +

mach_port_extract_right

+
+

+Function - Remove the specified right from the target task and return it to the caller. +

SYNOPSIS

+
+kern_return_t   mach_port_extract_right
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_msg_type_name_t              desired_type,
+                 mach_port_poly_t                        *right,
+                 mach_msg_type_name_             *acquired_type);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task holding the port right. +

+

name +
+[in scalar] +The task's name for the port right. +

+

desired_type +
+[in scalar] +IPC type, specifying how the right should be extracted. +

+

right +
+[out random right] +The extracted right. +

+

acquired_type +
+[out scalar] +The type of the extracted right. +
+

DESCRIPTION

+

+The mach_port_extract_right function extracts a port +right from the target +task and returns it to the caller as if the task sent the right +voluntarily, using +desired_type as the disposition for the right. See mach_msg. +

+The returned value of acquired_type will be +MACH_MSG_TYPE_PORT_SEND if a send right is extracted, +MACH_MSG_TYPE_PORT_RECEIVE if a +receive right is extracted, and MACH_MSG_TYPE_PORT_SEND_ONCE if a +send-once right is extracted. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+name did not denote a right. +

+

KERN_INVALID_RIGHT +
+name denoted an invalid right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_insert_right, +mach_msg. 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 @@ -

mach_port_get_attributes

Function - Return information about target port as specified by the caller.

SYNOPSIS

kern_return_t   mach_port_get_attributes
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_port_flavor_t                      flavor,
                 mach_port_info_t                     port_info,
                 mach_msg_type_number_t        *port_info_count);

PARAMETERS

task
[in task send right] The task holding a receive right to the port in question.

name
[in scalar] task's name for the port.

flavor
[in scalar] The type of information to be returned. Valid values are:

MACH_PORT_LIMITS_INFO
Returns the resource limits for the port. The declaration of this data is found in structure mach_port_limits.

MACH_PORT_RECEIVE_STATUS
Returns random information about the rights and messages associated with the port. The declaration of this data is found in structure mach_port_status.

port_info
[out structure] Information about the specified port.

port_info_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The mach_port_get_attributes function returns an information structure of type flavor.

NOTES

This interface is machine word length specific because of the port name parameter in the MACH_PORT_RECEIVE_STATUS structure return.

RETURN VALUES

KERN_INVALID_NAME
name did not denote a right.

KERN_INVALID_RIGHT
name denoted a right, but not a receive right.

RELATED INFORMATION

Functions: mach_port_allocate, mach_port_allocate_name, mach_port_set_attributes.

Data Structures: mach_port_limits, mach_port_status. \ No newline at end of file +

mach_port_get_attributes

+
+

+Function - Return information about target port as specified by the caller. +

SYNOPSIS

+
+kern_return_t   mach_port_get_attributes
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_port_flavor_t                      flavor,
+                 mach_port_info_t                     port_info,
+                 mach_msg_type_number_t        *port_info_count);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task holding a receive right to the port in +question. +

+

name +
+[in scalar] +task's name for the port. +

+

flavor +
+[in scalar] +The type of information to be returned. Valid values are: +
+

+

MACH_PORT_LIMITS_INFO +
+Returns the resource limits for the port. The declaration of +this data is found in structure mach_port_limits. +

+

MACH_PORT_RECEIVE_STATUS +
+Returns random information about the rights and messages +associated with the port. The declaration of this data is found in +structure mach_port_status. +
+

+

port_info +
+[out structure] +Information about the specified port. +

+

port_info_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The mach_port_get_attributes function returns an information +structure of type flavor. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter in the MACH_PORT_RECEIVE_STATUS structure return. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+name did not denote a right. +

+

KERN_INVALID_RIGHT +
+name denoted a right, but not a receive right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate, +mach_port_allocate_name, +mach_port_set_attributes. +

+Data Structures: +mach_port_limits, +mach_port_status. 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 @@ -

mach_port_get_refs

Function - Return the current count of user references on the target port right.

SYNOPSIS

kern_return_t   mach_port_get_refs
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_port_right_t                        right,
                 mach_port_urefs_t                        *refs);

PARAMETERS

task
[in task send right] The task holding the right.

name
[in scalar] The task's name for the right.

right
[in scalar] The type of right/entity being examined:

MACH_PORT_RIGHT_SEND

MACH_PORT_RIGHT_RECEIVE

MACH_PORT_RIGHT_SEND_ONCE

MACH_PORT_RIGHT_PORT_SET

MACH_PORT_RIGHT_DEAD_NAME

refs
[out scalar] Number of user references.

DESCRIPTION

The mach_port_get_refs function returns the number of user references a task has for a right.

If name 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.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
name did not denote a right.

RELATED INFORMATION

Functions: mach_port_mod_refs. \ No newline at end of file +

mach_port_get_refs

+
+

+Function - Return the current count of user references on the target port right. +

SYNOPSIS

+
+kern_return_t   mach_port_get_refs
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_port_right_t                        right,
+                 mach_port_urefs_t                        *refs);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task holding the right. +

+

name +
+[in scalar] +The task's name for the right. +

+

right +
+[in scalar] +The type of right/entity being examined: +
+

+

+MACH_PORT_RIGHT_SEND +

+

+MACH_PORT_RIGHT_RECEIVE +

+

+MACH_PORT_RIGHT_SEND_ONCE +

+

+MACH_PORT_RIGHT_PORT_SET +

+

+MACH_PORT_RIGHT_DEAD_NAME +
+

+

refs +
+[out scalar] +Number of user references. +
+

DESCRIPTION

+

+The mach_port_get_refs function returns the number +of user references a task +has for a right. +

+If name 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. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+name did not denote a right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_mod_refs. 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 @@ -

mach_port_get_set_status

Function - Return the port right names contained in the target port set.

SYNOPSIS

kern_return_t   mach_port_get_set_status
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_port_name_array_t                *members,
                 task                                     count);

PARAMETERS

task
[in task send right] The task holding the port set.

name
[in scalar] The task's name for the port set.

members
[out pointer to dynamic array of mach_port_name_t] The task's names for the port set's members.

count
[out scalar] The number of member names returned.

DESCRIPTION

The mach_port_get_set_status function returns the individual port right names for all port rights contained in the specified port set. The members parameter is an array that is automatically allocated when the reply message is received. Note that vm_deallocate should be used to free the array.

Note that this interface, unlike others such as task_threads, 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 mach_port_get_set_status does not affect the reference count of each port right within the target port set.

NOTES

This interface is machine word length specific because of the port name parameter and the returned port names.

RETURN VALUES

KERN_INVALID_NAME
name did not denote a right.

KERN_INVALID_RIGHT
name denoted a right, but not a port set.

RELATED INFORMATION

Functions: mach_port_insert_member, mach_port_extract_member, mach_port_move_member, vm_deallocate. \ No newline at end of file +

mach_port_get_set_status

+
+

+Function - Return the port right names contained in the target port set. +

SYNOPSIS

+
+kern_return_t   mach_port_get_set_status
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_port_name_array_t                *members,
+                 task                                     count);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task holding the port set. +

+

name +
+[in scalar] +The task's name for the port set. +

+

members +
+[out pointer to dynamic array of mach_port_name_t] +The task's names +for the port set's members. +

+

count +
+[out scalar] +The number of member names returned. +
+

DESCRIPTION

+

+The mach_port_get_set_status function returns the individual port +right names for all port rights contained in the specified port set. +The members parameter is an array that is automatically +allocated when the reply message is received. Note that +vm_deallocate should be used to free the array. +

+Note that this interface, unlike others such as task_threads, +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 mach_port_get_set_status +does not affect the reference count of each port right within the target port set. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter and the returned port names. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+name did not denote a right. +

+

KERN_INVALID_RIGHT +
+name denoted a right, but not a port set. +
+

RELATED INFORMATION

+

+Functions: +mach_port_insert_member, +mach_port_extract_member, +mach_port_move_member, +vm_deallocate. 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 @@ - mach_port_insert_member.html

mach_port_insert_member

Function - Move the specified receive right into or out of the specified port set.

SYNOPSIS

kern_return_t   mach_port_insert_member
                (ipc_space_t                               task,
                 mach_port_name_t                        member,
                 mach_port_name_t                         set);

PARAMETERS

task
[in task send right] The task holding the port set and receive right.
member
[in scalar] The task's name for the receive right.
set
[in scalar] The task's name for the port set.

DESCRIPTION

The mach_port_insert_member 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.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
member or set did not denote a right.
KERN_INVALID_RIGHT
member denoted a right, but not a receive right, or set denoted a right, but not a port set.

RELATED INFORMATION

Functions: mach_port_extract_member, mach_port_move_member, mach_port_get_set_status, mach_port_get_attributes. \ No newline at end of file + + + + + + mach_port_insert_member.html + + + +

+mach_port_insert_member

+ +
+

Function - Move the specified receive right into or out of the +specified port set. +

+SYNOPSIS

+ +
kern_return_t   mach_port_insert_member
+                (ipc_space_t                               task,
+                 mach_port_name_t                        member,
+                 mach_port_name_t                         set);
+ +

+PARAMETERS

+ +
+
+task
+ +
+[in task send right] The task holding the port set and receive right.
+ +
+member
+ +
+[in scalar] The task's name for the receive right.
+ +
+set
+ +
+[in scalar] The task's name for the port set.
+
+ +

+DESCRIPTION

+The mach_port_insert_member 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. +

+NOTES

+This interface is machine word length specific because of the port name +parameter. +

+RETURN VALUES

+ +
+
+KERN_INVALID_NAME
+ +
+member or set did not denote a right.
+ +
+KERN_INVALID_RIGHT
+ +
+member denoted a right, but not a receive right, or set denoted +a right, but not a port set.
+
+ +

+RELATED INFORMATION

+Functions: +mach_port_extract_member, +mach_port_move_member, +mach_port_get_set_status, +mach_port_get_attributes. + + 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 @@ -

mach_port_insert_right

Function - Insert the specified port right into the target task.

SYNOPSIS

kern_return_t   mach_port_insert_right
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_port_poly_t                         right,
                 mach_msg_type_name_t                right_type);

PARAMETERS

task
[in task send right] The task which gets the caller's right.

name
[in scalar] The name by which task will know the right.

right
[in random right] The port right.

right_type
[in scalar] IPC type of the sent right; e.g., MACH_MSG_TYPE_COPY_SEND or MACH_MSG_TYPE_MOVE_RECEIVE.

DESCRIPTION

The mach_port_insert_right function inserts into task the caller's right for a port, using a specified name for the right in the target task.

The specified name can't be one of the reserved values MACH_PORT_NULL or MACH_PORT_DEAD. The right can't be MACH_PORT_NULL or MACH_PORT_DEAD.

The argument right_type specifies a right to be inserted and how that right should be extracted from the caller. It should be a value appropriate for mach_msg.

If right_type is MACH_MSG_TYPE_MAKE_SEND, MACH_MSG_TYPE_MOVE_SEND, or MACH_MSG_TYPE_COPY_SEND, then a send right is inserted. If the target already holds send or receive rights for the port, then name should denote those rights in the target. Otherwise, name 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.

If right_type is MACH_MSG_TYPE_MAKE_SEND_ONCE or MACH_MSG_TYPE_MOVE_SEND_ONCE, then a send-once right is inserted. The name should be unused in the target. The target gains a send-once right.

If right_type is MACH_MSG_TYPE_MOVE_RECEIVE, then a receive right is inserted. If the target already holds send rights for the port, then name should denote those rights in the target. Otherwise, name should be unused in the target. The receive right is moved into the target task.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_NAME_EXISTS
name already denoted a right.

KERN_INVALID_CAPABILITY
right was null or dead.

KERN_UREFS_OVERFLOW
Inserting the right would overflow name's user-reference count.

KERN_RIGHT_EXISTS
task already had rights for the port, with a different name.

RELATED INFORMATION

Functions: mach_port_extract_right, mach_msg. \ No newline at end of file +

mach_port_insert_right

+
+

+Function - Insert the specified port right into the target task. +

SYNOPSIS

+
+kern_return_t   mach_port_insert_right
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_port_poly_t                         right,
+                 mach_msg_type_name_t                right_type);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task which gets the caller's right. +

+

name +
+[in scalar] +The name by which task will know the right. +

+

right +
+[in random right] +The port right. +

+

right_type +
+[in scalar] +IPC type of the sent right; e.g., +MACH_MSG_TYPE_COPY_SEND or MACH_MSG_TYPE_MOVE_RECEIVE. +
+

DESCRIPTION

+

+The mach_port_insert_right function inserts into task +the caller's right for a +port, using a specified name for the right in the target task. +

+The specified name can't be one of the reserved values MACH_PORT_NULL +or MACH_PORT_DEAD. The right can't be MACH_PORT_NULL or +MACH_PORT_DEAD. +

+The argument right_type specifies a right to be inserted and how that right +should be extracted from the caller. It should be a value appropriate for +mach_msg. +

+If right_type is MACH_MSG_TYPE_MAKE_SEND, MACH_MSG_TYPE_MOVE_SEND, +or +MACH_MSG_TYPE_COPY_SEND, then a send right is inserted. If the target +already holds send or receive rights for the port, then name +should denote those rights in the target. Otherwise, name 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. +

+If right_type is MACH_MSG_TYPE_MAKE_SEND_ONCE or +MACH_MSG_TYPE_MOVE_SEND_ONCE, then a send-once right is inserted. +The name should be unused in the target. The +target gains a send-once right. +

+If right_type is MACH_MSG_TYPE_MOVE_RECEIVE, then a receive right is +inserted. If the target already holds send rights for the port, +then name should +denote those rights in the target. Otherwise, name should be +unused in the target. +The receive right is moved into the target task. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_NAME_EXISTS +
+name already denoted a right. +

+

KERN_INVALID_CAPABILITY +
+right was null or dead. +

+

KERN_UREFS_OVERFLOW +
+Inserting the right would overflow name's user-reference count. +

+

KERN_RIGHT_EXISTS +
+task already had rights for the port, with a different name. +
+

RELATED INFORMATION

+

+Functions: +mach_port_extract_right, +mach_msg. 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 @@ -

mach_port_limits

Structure - Specifies a port's resource and message queue limits.

SYNOPSIS

struct mach_port_limits
{
       mach_port_msgcount_t      queue_limit;
};

typedef struct mach_port_limits* mach_port_limits_t;

FIELDS

queue_limit
Number of messages allowed to be on the message queue at any given time. Attempts to queue more messages than this limit will block.

DESCRIPTION

The mach_port_limits 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.)

RELATED INFORMATION

Functions: mach_port_get_attributes, mach_port_set_attributes.

Structures: mach_port_qos. \ No newline at end of file +

mach_port_limits

+
+

+Structure - Specifies a port's resource and message queue limits. +

SYNOPSIS

+
+struct mach_port_limits
+{
+       mach_port_msgcount_t      queue_limit;
+};
+
+typedef struct mach_port_limits* mach_port_limits_t;
+
+

FIELDS

+
+
queue_limit +
+Number of messages allowed to be on the message queue at any given +time. Attempts to queue more messages than this limit will block. +
+

DESCRIPTION

+

+The mach_port_limits 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.) +

RELATED INFORMATION

+

+Functions: +mach_port_get_attributes, +mach_port_set_attributes. +

+Structures: +mach_port_qos. + 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 @@ -

mach_port_mod_refs

Function - Modify the specified port right's count of user references.

SYNOPSIS

kern_return_t   mach_port_mod_refs
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_port_right_t                        right,
                 mach_port_delta_t                        delta);

PARAMETERS

task
[in task send right] The task holding the right.

name
[in scalar] The task's name for the right.

right
[in scalar] The type of right/entity being modified:

MACH_PORT_RIGHT_SEND

MACH_PORT_RIGHT_RECEIVE

MACH_PORT_RIGHT_SEND_ONCE

MACH_PORT_RIGHT_PORT_SET

MACH_PORT_RIGHT_DEAD_NAME

delta
[in scalar] Signed change to the number of user references.

DESCRIPTION

The mach_port_mod_refs 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.

The name parameter should denote the specified right. The number of user references for the right is changed by the amount delta, 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.

If the call destroys the right, then the effect is as described for mach_port_destroy, with the exception that mach_port_destroy simultaneously destroys all the rights denoted by a name, while mach_port_mod_refs can only destroy one right. The name will be available for reuse if it only denoted the one right.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
name did not denote a right.

KERN_INVALID_RIGHT
name denoted a right, but not the specified right.

KERN_INVALID_VALUE
The user-reference count would become negative.

KERN_UREFS_OVERFLOW
The user-reference count would overflow.

RELATED INFORMATION

Functions: mach_port_destroy, mach_port_get_refs. \ No newline at end of file +

mach_port_mod_refs

+
+

+Function - Modify the specified port right's count of user references. +

SYNOPSIS

+
+kern_return_t   mach_port_mod_refs
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_port_right_t                        right,
+                 mach_port_delta_t                        delta);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task holding the right. +

+

name +
+[in scalar] +The task's name for the right. +

+

right +
+[in scalar] +The type of right/entity being modified: +
+

+

+MACH_PORT_RIGHT_SEND +

+

+MACH_PORT_RIGHT_RECEIVE +

+

+MACH_PORT_RIGHT_SEND_ONCE +

+

+MACH_PORT_RIGHT_PORT_SET +

+

+MACH_PORT_RIGHT_DEAD_NAME +
+

+

delta +
+[in scalar] +Signed change to the number of user references. +
+

DESCRIPTION

+

+The mach_port_mod_refs 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. +

+The name parameter +should denote the specified right. The number of user references for +the right is changed by the amount delta, 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. +

+If the call destroys the right, then the effect is as described for +mach_port_destroy, with the exception that +mach_port_destroy +simultaneously destroys all +the rights denoted by a name, while mach_port_mod_refs +can only destroy +one right. The name will be available for reuse if it only denoted +the one right. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+name did not denote a right. +

+

KERN_INVALID_RIGHT +
+name denoted a right, but not the specified right. +

+

KERN_INVALID_VALUE +
+The user-reference count would become negative. +

+

KERN_UREFS_OVERFLOW +
+The user-reference count would overflow. +
+

RELATED INFORMATION

+

+Functions: +mach_port_destroy, +mach_port_get_refs. 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 @@ - mach_port_insert_member.html

mach_port_move_member

Function - Move the specified receive right into or out of the specified port set.

SYNOPSIS

kern_return_t   mach_port_move_member
                (ipc_space_t                               task,
                 mach_port_name_t                        member,
                 mach_port_name_t                         after);

PARAMETERS

task
[in task send right] The task holding the port set and receive right.
member
[in scalar] The task's name for the receive right.
after
[in scalar] The task's name for the port set.

DESCRIPTION

The mach_port_move_member 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 MACH_PORT_NULL, then the receive right is not put into a port set, but removed from all its current port sets.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
member or after did not denote a right.
KERN_INVALID_RIGHT
member denoted a right, but not a receive right, or after denoted a right, but not a port set.
KERN_NOT_IN_SET
after was MACH_PORT_NULL, but member wasn't currently in a port set.

RELATED INFORMATION

Functions: mach_port_insert_member, mach_port_extract_member, mach_port_get_set_status, mach_port_get_attributes.

\ No newline at end of file + + + + + + mach_port_insert_member.html + + + +

+mach_port_move_member

+ +
+

Function - Move the specified receive right into or out of the +specified port set. +

+SYNOPSIS

+ +
kern_return_t   mach_port_move_member
+                (ipc_space_t                               task,
+                 mach_port_name_t                        member,
+                 mach_port_name_t                         after);
+ +

+PARAMETERS

+ +
+
+task
+ +
+[in task send right] The task holding the port set and receive right.
+ +
+member
+ +
+[in scalar] The task's name for the receive right.
+ +
+after
+ +
+[in scalar] The task's name for the port set.
+
+ +

+DESCRIPTION

+The mach_port_move_member 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 MACH_PORT_NULL, +then the receive right is not put into a port set, but removed from all +its current port sets. +

+NOTES

+This interface is machine word length specific because of the port name +parameter. +

+RETURN VALUES

+ +
+
+KERN_INVALID_NAME
+ +
+member or after did not denote a right.
+ +
+KERN_INVALID_RIGHT
+ +
+member denoted a right, but not a receive right, or after +denoted a right, but not a port set.
+ +
+KERN_NOT_IN_SET
+ +
+after was MACH_PORT_NULL, but member wasn't currently +in a port set.
+
+ +

+RELATED INFORMATION

+ +

+Functions: +mach_port_insert_member, +mach_port_extract_member, +mach_port_get_set_status, +mach_port_get_attributes. +

+ + + 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 @@ -

mach_port_names

Function - Return information about a task's port name space.

SYNOPSIS

kern_return_t   mach_port_names
                (ipc_space_t                               task,
                 mach_port_name_array_t                  *names,
                 mach_msg_type_number_t               *namesCnt,
                 mach_port_type_array_                   *types,
                 mach_msg_type_number_t               *typesCnt);

PARAMETERS

task
[in task send right] The task whose port name space is queried.

names
[out pointer to dynamic array of mach_port_name_t] The names of the ports, port sets, and dead names in the task's port name space, in no particular order.

namesCnt
[out scalar] The number of names returned.

types
[out pointer to dynamic array of mach_port_type_t] The type of each corresponding name. Indicates what kind of rights the task holds with that name.

typesCnt
[out scalar] The number of types returned.

DESCRIPTION

The mach_port_names returns information about task'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 task holds (the same information returned by mach_port_type).

Note that when a call to mach_port_names returns, the number of entries in the two output arrays (names and types) are equal (namesCnt equals typesCnt). The fact that this interface returns two separate counts is an artifact of the Mach Interface Generator.

NOTES

This interface is machine word length specific because of the port name parameter and the returned port names.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_port_type. \ No newline at end of file +

mach_port_names

+
+

+Function - Return information about a task's port name space. +

SYNOPSIS

+
+kern_return_t   mach_port_names
+                (ipc_space_t                               task,
+                 mach_port_name_array_t                  *names,
+                 mach_msg_type_number_t               *namesCnt,
+                 mach_port_type_array_                   *types,
+                 mach_msg_type_number_t               *typesCnt);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task whose port name space is queried. +

+

names +
+[out pointer to dynamic array of mach_port_name_t] +The names of the +ports, port sets, and dead names in the task's port name space, in no +particular order. +

+

namesCnt +
+[out scalar] +The number of names returned. +

+

types +
+[out pointer to dynamic array of mach_port_type_t] +The type of each +corresponding name. Indicates what kind of rights the task holds with +that name. +

+

typesCnt +
+[out scalar] +The number of types returned. +
+

DESCRIPTION

+

+The mach_port_names returns information about task'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 +task holds (the +same information returned by mach_port_type). +

+Note that when a call to mach_port_names returns, the +number of entries in the two output arrays (names and types) +are equal (namesCnt equals typesCnt). The fact that this +interface returns two separate counts is an artifact of the Mach Interface Generator. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter and the returned port names. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_port_type. 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 @@ -

mach_port_qos

Structure - Specifies a port's attributes with respect to "Quality Of Service."

SYNOPSIS

typedef struct mach_port_qos
        {
               boolean_t      name;
               boolean_t      rt;
               boolean_t      pad1;
               boolean_t      pad2;
        } mach_port_qos_t;

FIELDS

name
If TRUE, the system will bestow the user-specified name on the newly allocated port. Otherwise, the system will choose the port's name.

rt
If TRUE, this field causes a realtime port to be allocated. Otherwise, a regular port will be allocated.

pad1
A 30 bit padding field.

pad2
A 32 bit padding field; with the pad1 field, lengthens the structure to 64 bits.

DESCRIPTION

The mach_port_qos structure is used to specify a port's "quality of service" attributes when allocating the port via the mach_port_allocate_qos interface.

RELATED INFORMATION

Functions: mach_port_allocate_qos, mach_port_get_attributes, mach_port_set_attributes. \ No newline at end of file +

mach_port_qos

+
+

+Structure - Specifies a port's attributes with respect to "Quality Of Service." +

SYNOPSIS

+
+typedef struct mach_port_qos
+        {
+               boolean_t      name;
+               boolean_t      rt;
+               boolean_t      pad1;
+               boolean_t      pad2;
+        } mach_port_qos_t;
+
+

FIELDS

+
+
name +
+ If TRUE, the system will bestow the user-specified name on the newly allocated port. + Otherwise, the system will choose the port's name. +

+

rt +
+ If TRUE, this field causes a realtime port to be allocated. + Otherwise, a regular port will be allocated. +

+

pad1 +
+ A 30 bit padding field. +

+

pad2 +
+A 32 bit padding field; with the pad1 field, lengthens the + structure to 64 bits. +
+

DESCRIPTION

+

+The mach_port_qos structure is used to specify a port's +"quality of service" attributes when allocating the port via the +mach_port_allocate_qos interface. +

RELATED INFORMATION

+

+Functions: +mach_port_allocate_qos, +mach_port_get_attributes, +mach_port_set_attributes. 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 @@ -

mach_port_set_attributes

Function - Set the target port's attributes.

SYNOPSIS

kern_return_t   mach_port_set_attributes
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_port_flavor_t                      flavor,
                 mach_port_info_t                     port_info,
                 mach_msg_type_number_t         port_info_count);

PARAMETERS

task
[in task send right] The task holding a receive right to the port in question.

name
[in scalar] task's name for the port.

flavor
[in scalar] The type of attributes to be set. Valid values are:

MACH_PORT_LIMITS_INFO
Sets resource limits (queue limits) for the port. The declaration of this data is found in structure mach_port_limits.

port_info
[pointer to in structure] Attributes for the specified port.

port_info_count
[in scalar] The size of the buffer (in natural-sized units).

DESCRIPTION

The mach_port_set_attributes function sets attributes of type flavor.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
name did not denote a right.

KERN_INVALID_RIGHT
name denoted a right, but not a receive right.

RELATED INFORMATION

Functions: mach_port_allocate, mach_port_allocate_name, mach_port_get_attributes.

Data Structures: mach_port_limits. \ No newline at end of file +

mach_port_set_attributes

+
+

+Function - Set the target port's attributes. +

SYNOPSIS

+
+kern_return_t   mach_port_set_attributes
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_port_flavor_t                      flavor,
+                 mach_port_info_t                     port_info,
+                 mach_msg_type_number_t         port_info_count);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task holding a receive right to the port in +question. +

+

name +
+[in scalar] +task's name for the port. +

+

flavor +
+[in scalar] +The type of attributes to be set. Valid values are: +
+

+

MACH_PORT_LIMITS_INFO +
+Sets resource limits (queue limits) for the port. The declaration +of this data is found in structure mach_port_limits. +
+

+

port_info +
+[pointer to in structure] +Attributes for the specified port. +

+

port_info_count +
+[in scalar] +The size of the buffer (in natural-sized units). +
+ +

DESCRIPTION

+

+The mach_port_set_attributes function sets attributes of type +flavor. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+name did not denote a right. +

+

KERN_INVALID_RIGHT +
+name denoted a right, but not a receive right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate, +mach_port_allocate_name, +mach_port_get_attributes. +

+Data Structures: +mach_port_limits. 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 @@ -

mach_port_set_mscount

Function - Change the target port's make-send count.

SYNOPSIS

kern_return_t   mach_port_set_mscount
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_port_mscount_t                    mscount);

PARAMETERS

task
[in task send right] The task owning the receive right.

name
[in scalar] task's name for the receive right.

mscount
[in scalar] New value for the make-send count for the receive right.

DESCRIPTION

The mach_port_set_mscount function changes the make-send count of task's receive right named name. 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.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
name did not denote a right.

KERN_INVALID_RIGHT
name denoted a right, but not a receive right.

RELATED INFORMATION

Functions: mach_port_get_attributes. \ No newline at end of file +

mach_port_set_mscount

+
+

+Function - Change the target port's make-send count. +

SYNOPSIS

+
+kern_return_t   mach_port_set_mscount
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_port_mscount_t                    mscount);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task owning the receive right. +

+

name +
+[in scalar] +task's name for the receive right. +

+

mscount +
+[in scalar] +New value for the make-send count for the receive right. +
+

DESCRIPTION

+

+The mach_port_set_mscount function changes the make-send +count of task's +receive right named name. +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. +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+name did not denote a right. +

+

KERN_INVALID_RIGHT +
+name denoted a right, but not a receive right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_get_attributes. 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 @@ -

mach_port_set_seqno

Function - Change the current value of the target port's sequence number.

SYNOPSIS

kern_return_t   mach_port_set_seqno
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_port_seqno_t                        seqno);

PARAMETERS

task
[in task send right] The task owning the receive right.

name
[in scalar] task's name for the receive right.

seqno
[in scalar] The sequence number that the next message received from the port will have.

DESCRIPTION

The mach_port_set_seqno function changes the sequence number of task's receive right named name.

(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.)

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
name did not denote a right.

KERN_INVALID_RIGHT
name denoted a right, but not a receive right.

RELATED INFORMATION

Functions: mach_port_get_attributes. \ No newline at end of file +

mach_port_set_seqno

+
+

+Function - Change the current value of the target port's sequence number. +

SYNOPSIS

+
+kern_return_t   mach_port_set_seqno
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_port_seqno_t                        seqno);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task owning the receive right. +

+

name +
+[in scalar] +task's name for the receive right. +

+

seqno +
+[in scalar] +The sequence number that the next message received from +the port will have. +
+

DESCRIPTION

+

+The mach_port_set_seqno function changes the sequence +number of task's +receive right named name. +

+(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.) +

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+name did not denote a right. +

+

KERN_INVALID_RIGHT +
+name denoted a right, but not a receive right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_get_attributes. 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 @@ -

mach_port_status

Structure - Used to present a port's current status with respect to various important attributes.

SYNOPSIS

struct mach_port_status
{
       natural_t                mps_pset_count;
       mach_port_seqno_t         mps_seqno;
       mach_port_mscount_t     mps_mscount;
       mach_port_msgcount_t     mps_qlimit;
       mach_port_msgcount_t   mps_msgcount;
       mach_port_rights_t     mps_sorights;
       mach_port_srights_t     mps_srights;
       boolean_t             mps_pdrequest;
       boolean_t             mps_nsrequest;
       unsigned int              mps_flags;
};

typedef struct mach_port_status mach_port_status_t;

FIELDS

mps_pset
Containing port set.

mps_seqno
Current sequence number for the port.

mps_mscount
Make-send count.

mps_msgcount
Upper limit for the number of messages that may be queued to the port before the system blocks send operations.

mps_msgcount
Number of messages currently queued on the port.

mps_sorights
How many send-once rights.

mps_srights
Specifies whether or not send rights exist. Valid values are as follows:

MPS_FALSE
No send rights currently in existence.

MPS_TRUE
Send rights exist and no-more-senders notification is enabled.

MPS_UNKNOWN
The port does not permit no-more-senders notification requests; consequently, the system does not know whether or not send rights exist.

mps_pdrequest
Specifies whether or not a port-deleted notification has been requested.

mps_nsrequest
True if no-senders requested.

mps_flags
Flags associated with the port.

DESCRIPTION

The mach_port_status structure is used to provide information about a port in response to an invocation of the mach_port_get_attributes interface.

NOTES

This structure is machine word length sensitive due to the presence of the port set name.

RELATED INFORMATION

Functions: mach_port_get_attributes. \ No newline at end of file +

mach_port_status

+
+

+Structure - Used to present a port's current status with respect to various important attributes. +

SYNOPSIS

+
+struct mach_port_status
+{
+       natural_t                mps_pset_count;
+       mach_port_seqno_t         mps_seqno;
+       mach_port_mscount_t     mps_mscount;
+       mach_port_msgcount_t     mps_qlimit;
+       mach_port_msgcount_t   mps_msgcount;
+       mach_port_rights_t     mps_sorights;
+       mach_port_srights_t     mps_srights;
+       boolean_t             mps_pdrequest;
+       boolean_t             mps_nsrequest;
+       unsigned int              mps_flags;
+};
+
+typedef struct mach_port_status mach_port_status_t;
+
+

FIELDS

+
+
mps_pset +
+Containing port set. +

+

mps_seqno +
+Current sequence number for the port. +

+

mps_mscount +
+ Make-send count. +

+

mps_msgcount +
+Upper limit for the number of messages that may be queued to the port + before the system blocks send operations. +

+

mps_msgcount +
+ Number of messages currently queued on the port. +

+

mps_sorights +
+How many send-once rights. +

+

mps_srights +
+Specifies whether or not send rights exist. Valid values are as follows: +
+

+

MPS_FALSE +
+ No send rights currently in existence. +

+

MPS_TRUE +
+ Send rights exist and no-more-senders notification is enabled. +

+

MPS_UNKNOWN +
+ The port does not permit no-more-senders notification requests; + consequently, the system does not know whether or not send rights + exist. +
+

+

mps_pdrequest +
+ Specifies whether or not a port-deleted notification has been requested. +

+

mps_nsrequest +
+True if no-senders requested. +

+

mps_flags +
+ Flags associated with the port. +
+

DESCRIPTION

+

+The mach_port_status structure is used to provide +information about a port in response to an invocation of the +mach_port_get_attributes interface. +

NOTES

+

+This structure is machine word length sensitive due +to the presence of the port +set name. +

RELATED INFORMATION

+

+Functions: +mach_port_get_attributes. 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 @@ -

mach_port_type

Function - Return the characteristics of the target port name.

SYNOPSIS

kern_return_t   mach_port_type
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_port_type_t                         ptype);

PARAMETERS

task
[in task send right] The task whose port name space is queried.

name
[in scalar] The name being queried.

ptype
[out scalar] The type of the name. Indicates what kind of right the task holds for the port, port set, or dead name.

DESCRIPTION

The mach_port_type function returns information about task's rights for a specific name in its port name space. The returned ptype is a bit-mask indicating what rights task holds with this name. The bit-mask is composed of the following bits:

MACH_PORT_TYPE_SEND
The name denotes send rights.

MACH_PORT_TYPE_RECEIVE
The name denotes a receive right.

MACH_PORT_TYPE_SEND_ONCE
The name denotes a send-once right.

MACH_PORT_TYPE_PORT_SET
The name denotes a port set.

MACH_PORT_TYPE_DEAD_NAME
The name is a dead name.

MACH_PORT_TYPE_DNREQUEST
A dead-name request has been registered for the right.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

KERN_INVALID_NAME
name did not denote a right.

RELATED INFORMATION

Functions: mach_port_names, mach_port_get_attributes, mach_port_get_set_status. \ No newline at end of file +

mach_port_type

+
+

+Function - Return the characteristics of the target port name. +

SYNOPSIS

+
+kern_return_t   mach_port_type
+                (ipc_space_t                               task,
+                 mach_port_name_t                          name,
+                 mach_port_type_t                         ptype);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task whose port name space is queried. +

+

name +
+[in scalar] +The name being queried. +

+

ptype +
+[out scalar] +The type of the name. Indicates what kind of right the task +holds for the port, port set, or dead name. +
+

DESCRIPTION

+

+The mach_port_type function returns information about task's +rights for a specific name in its port name space. The returned +ptype is a bit-mask indicating what rights task +holds with this name. +The bit-mask is composed of the following bits: +

+
MACH_PORT_TYPE_SEND +
+The name denotes send rights. +

+

MACH_PORT_TYPE_RECEIVE +
+The name denotes a receive right. +

+

MACH_PORT_TYPE_SEND_ONCE +
+The name denotes a send-once right. +

+

MACH_PORT_TYPE_PORT_SET +
+The name denotes a port set. +

+

MACH_PORT_TYPE_DEAD_NAME +
+The name is a dead name. +

+

MACH_PORT_TYPE_DNREQUEST +
+A dead-name request has been registered for the right. +
+

NOTES

+

+This interface is machine word length specific because of the port name +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_NAME +
+name did not denote a right. +
+

RELATED INFORMATION

+

+Functions: +mach_port_names, +mach_port_get_attributes, +mach_port_get_set_status. 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 @@ -

mach_ports_lookup

Function - Provide caller with an array of the target task's well-known ports.

SYNOPSIS

kern_return_t   mach_ports_lookup
                (task_t                             target_task,
                 mach_port_array_t                init_port_set,
                 mach_msg_type_number_t         init_port_count);

PARAMETERS

target_task
[in task send right] The task whose currently registered ports are to be returned.

init_port_set
[out pointer to dynamic array of registered send rights] The returned array of ports.

init_port_count
[out scalar] The number of returned port rights.

DESCRIPTION

The mach_ports_lookup 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.

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 mach_ports_register function.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_ports_register. \ No newline at end of file +

mach_ports_lookup

+
+

+Function - Provide caller with an array of the target task's well-known ports. +

SYNOPSIS

+
+kern_return_t   mach_ports_lookup
+                (task_t                             target_task,
+                 mach_port_array_t                init_port_set,
+                 mach_msg_type_number_t         init_port_count);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The task whose currently registered ports are to be +returned. +

+

init_port_set +
+[out pointer to dynamic array of registered send rights] +The returned +array of ports. +

+

init_port_count +
+[out scalar] +The number of returned port rights. +
+

DESCRIPTION

+

+The mach_ports_lookup 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. +

+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 mach_ports_register function. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_ports_register. 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 @@ -

mach_ports_register

Function - Register an array of well-known ports on behalf of the target task.

SYNOPSIS

kern_return_t   mach_ports_register
                (task_t                             target_task,
                 mach_port_array_t                init_port_set,
                 target_task              init_port_array_count);

PARAMETERS

target_task
[in task send right] The task for which the ports are to be registered.

init_port_set
[in pointer to array of registered send rights] The array of ports to register.

init_port_array_count
[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 MACH_PORTS_SLOTS_USED.

DESCRIPTION

The mach_ports_register 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:

  • The port for the Name Server
  • The port for the Environment Manager
  • The port for the Service server

Each port must be placed in a specific slot in the array. The slot numbers are defined (in mach.h) by the global constants NAME_SERVER_SLOT, ENVIRONMENT_SLOT, and SERVICE_SLOT.

A task can retrieve the currently registered ports by using the mach_ports_lookup function.

NOTES

When a new task is created (with task_create), 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 mach_ports_lookup to get them. It is intended that port registration be used only for task initialization, and then only by run-time support modules.

A parent task has three choices when passing registered ports to child tasks:

  • The parent task can do nothing. In this case, all child tasks inherit access to the same ports that the parent has.
  • The parent task can use mach_ports_register 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 mach_ports_register again to reset its registered ports.
  • The parent task can first create a specific child task and then use mach_ports_register 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 mach_ports_register.

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.

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:

  • An initial message (see mach_msg).
  • The Name Server, for public ports.
  • The Environment Manager, for private ports.
  • The task bootstrap port (see task_get_special_port).

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_msg, mach_ports_lookup. \ No newline at end of file +

mach_ports_register

+
+

+Function - Register an array of well-known ports on behalf of the target task. +

SYNOPSIS

+
+kern_return_t   mach_ports_register
+                (task_t                             target_task,
+                 mach_port_array_t                init_port_set,
+                 target_task              init_port_array_count);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The task for which the ports are to be registered. +

+

init_port_set +
+[in pointer to array of registered send rights] +The array of ports to +register. +

+

init_port_array_count +
+[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 +MACH_PORTS_SLOTS_USED. +
+

DESCRIPTION

+

+The mach_ports_register 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: +

    +
  • +The port for the Name Server +
  • +The port for the Environment Manager +
  • +The port for the Service server +
+

+Each port must be placed in a specific slot in the array. The slot numbers are +defined (in mach.h) by the global constants NAME_SERVER_SLOT, +ENVIRONMENT_SLOT, and SERVICE_SLOT. +

+A task can retrieve the currently registered ports by using the +mach_ports_lookup function. +

NOTES

+

+When a new task is created (with task_create), +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 mach_ports_lookup to +get them. It is intended +that port registration be used only for task initialization, and then only by +run-time support modules. +

+A parent task has three choices when passing registered ports to child tasks: +

    +
  • +The parent task can do nothing. In this case, all child tasks +inherit access to +the same ports that the parent has. +
  • +The parent task can use mach_ports_register 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 +mach_ports_register again to reset its registered ports. +
  • +The parent task can first create a specific child task and then use +mach_ports_register 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 mach_ports_register. +
+

+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. +

+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: +

    +
  • +An initial message (see mach_msg). +
  • +The Name Server, for public ports. +
  • +The Environment Manager, for private ports. +
  • +The task bootstrap port (see task_get_special_port). +
+

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_msg, +mach_ports_lookup. 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 @@ -

mach_reply_port

System Trap - Allocate a new port and insert corresponding receive right in the calling task.

SYNOPSIS

#include<mach/mach_traps.h>

mach_port_t   mach_reply_port( void )

PARAMETERS

None.

DESCRIPTION

The mach_reply_port 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.

This function is an optimized version of mach_port_allocate 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.

If the task's task self port is null (thereby deactivating basic Mach manipulations by the task), this call returns null.

CAUTIONS

Although the created port can be used for any purpose, the implementation may optimize its use as a reply port.

RETURN VALUES

MACH_PORT_NULL
No port was allocated.

[reply receive right]
Any other value indicates success.

RELATED INFORMATION

Functions: mach_port_allocate. \ No newline at end of file +

mach_reply_port

+
+

+System Trap - Allocate a new port and insert corresponding receive right in the calling task. +

SYNOPSIS

+
+#include<mach/mach_traps.h>
+
+mach_port_t   mach_reply_port( void )
+
+

PARAMETERS

+
+None. +
+

DESCRIPTION

+

+The mach_reply_port 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. +

+This function is an optimized version of mach_port_allocate +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. +

+If the task's task self port is null (thereby deactivating basic Mach +manipulations by the task), this call returns null. +

CAUTIONS

+

+Although the created port can be used for any purpose, the implementation may +optimize its use as a reply port. +

RETURN VALUES

+
+
MACH_PORT_NULL +
+No port was allocated. +

+

[reply receive right] +
+Any other value indicates success. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate. 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 @@ -

mach_rpc_return_trap

System Trap - Real-Time RPC trap return location.

SYNOPSIS

#include<mach/rpc.h>

mach_rpc_return_t   mach_rpc_return_trap( void )

PARAMETERS

None.

DESCRIPTION

The mach_rpc_return_trap 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.

NOTES

This interface is experimental and therefore subject to change.

RETURN VALUES

The return value is specific to the server function actually executed via the mach_rpc_return_trap call.

RELATED INFORMATION

Functions: mach_rpc_trap. \ No newline at end of file +

mach_rpc_return_trap

+
+

+System Trap - Real-Time RPC trap return location. +

SYNOPSIS

+
+#include<mach/rpc.h>
+
+mach_rpc_return_t   mach_rpc_return_trap( void )
+
+

PARAMETERS

+

+None. +

DESCRIPTION

+

+The mach_rpc_return_trap 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. +

NOTES

+

+This interface is experimental and therefore subject to change. +

RETURN VALUES

+

+The return value is specific to the server function actually executed +via the mach_rpc_return_trap call. +

RELATED INFORMATION

+

+Functions: +mach_rpc_trap. 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 @@ -

mach_rpc_trap

System Trap - Real-Time RPC trap.

SYNOPSIS

#include<mach/rpc.h>

mach_rpc_return_t   mach_rpc_trap
                     (mach_port_t                    dest_port,
                      mach_rpc_id_t                routine_num,
                      mach_rpc_signature_t       signature_ptr,
                      mach_rpc_size_t           signature_size);

PARAMETERS

dest_port
[in send right] The port representing the destination of the RPC (usually a registered subsystem established by a call to mach_port_allocate_subsystem).

routine_num
[in scalar] Identifier of the server work function.

signature_ptr
[in pointer] Pointer to the call's mach_rpc_signature structure.

signature_size
[in scalar] Size, in bytes, of the call's mach_rpc_signature structure.

DESCRIPTION

The mach_rpc_trap 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 MACH_RPC macro which is invoked transparently when the mach_rpc 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.

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.

NOTES

This interface is experimental and therefore subject to change.

RETURN VALUES

KERN_FAILURE
Either the argument copyin failed, there were too many arguments, or the argument copyout failed.

KERN_INVALID_ARGUMENT
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.

KERN_NO_ACCESS
The kernel port associated with the dest_port name is a norma proxy port.

KERN_RESOURCE_SHORTAGE
The kernel could not allocate storage for an internal rpc state structure.

RELATED INFORMATION

Functions: mach_rpc_return_trap, thread_activation_create, mach_port_allocate_subsystem, mach_subsystem_create. \ No newline at end of file +

mach_rpc_trap

+
+

+System Trap - Real-Time RPC trap. +

SYNOPSIS

+
+#include<mach/rpc.h>
+
+mach_rpc_return_t   mach_rpc_trap
+                     (mach_port_t                    dest_port,
+                      mach_rpc_id_t                routine_num,
+                      mach_rpc_signature_t       signature_ptr,
+                      mach_rpc_size_t           signature_size);
+
+

PARAMETERS

+
+

+

dest_port +
+[in send right] The port representing the destination of the RPC + (usually a registered subsystem established by a call to + mach_port_allocate_subsystem). +

+

routine_num +
+[in scalar] Identifier of the server work function. +

+

signature_ptr +
+[in pointer] Pointer to the call's mach_rpc_signature structure. +

+

signature_size +
+[in scalar] Size, in bytes, of the call's mach_rpc_signature structure. +
+

DESCRIPTION

+

+The mach_rpc_trap 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 +MACH_RPC macro +which is invoked transparently when the mach_rpc 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. +

+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. +

NOTES

+

+This interface is experimental and therefore subject to change. +

RETURN VALUES

+
+

+

KERN_FAILURE +
+Either the argument copyin failed, there were too many arguments, or +the argument copyout failed. +

+

KERN_INVALID_ARGUMENT +
+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. +

+

KERN_NO_ACCESS +
+The kernel port associated with the dest_port name is a norma proxy +port. +

+

KERN_RESOURCE_SHORTAGE +
+The kernel could not allocate storage for an internal rpc state +structure. +
+

RELATED INFORMATION

+

+Functions: +mach_rpc_return_trap, +thread_activation_create, +mach_port_allocate_subsystem, +mach_subsystem_create. 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 @@ -

mach_subsystem_create

Function - Register information about an RPC subsystem.

SYNOPSIS

kern_return_t   mach_subsystem_create
                (task_t                             target_task,
                 user_subsystem_t                   user_subsys,
                 mach_msg_type_number_t          user_subsysCnt,
                 subsystem_t                        subsystem_t);

PARAMETERS

target_task
The task for which the subsystem is registered; normally the calling task, but not necessarily.

user_subsys
The MIG-generated data structure describing the exported routines and their input/output characteristics (e.g. arguments and return values).

user_subsysCnt
The size of the user_subsys data structure argument, in bytes.

subsys
The port returned that names the registered subsystem.

DESCRIPTION

The mach_subsystem_create 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 user_subsystem_t data structure that is appropriate for registering the subsystem. This data structure includes a per-routine array that specifies:

  • The address of the server function that performs the work.
  • The address of the MIG-generated server-side marshalling stub, to be used with mach_msg.
  • The argument signature (i.e. NDR-style argument format) of the routine.

Upon successful completion, mach_subsystem_create returns, via the subsys parameter, a port naming the registered subsystem.

Each port on which the server is to receive short-circuited RPC's (or a mach_rpc call) must be associated with a registered subsystem, by calling mach_port_allocate_subsystem.

RETURN VALUES

KERN_INVALD_ADDRESS
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).

KERN_INVALID_ARGUMENT
The port name specified by target_task is not a send right naming a task, or the subsystem size is too small to be valid.

KERN_INVALID_TASK
The target task is dead.

KERN_RESOURCE_SHORTAGE
The kernel cannot allocate the subsystem due to insufficient available memory.

RELATED INFORMATION

Functions: mach_port_allocate_subsystem, thread_activation_create. \ No newline at end of file +

mach_subsystem_create

+
+

+Function - Register information about an RPC subsystem. +

SYNOPSIS

+
+kern_return_t   mach_subsystem_create
+                (task_t                             target_task,
+                 user_subsystem_t                   user_subsys,
+                 mach_msg_type_number_t          user_subsysCnt,
+                 subsystem_t                        subsystem_t);
+
+

PARAMETERS

+
+

+

target_task +
+The task for which the subsystem is registered; normally the calling +task, but not necessarily. +

+

user_subsys +
+The MIG-generated data structure describing the exported routines and +their input/output characteristics (e.g. arguments and return values). +

+

user_subsysCnt +
+The size of the user_subsys data structure argument, in bytes. +

+

subsys +
+The port returned that names the registered subsystem. +
+

DESCRIPTION

+

+The mach_subsystem_create 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 +user_subsystem_t data structure that is appropriate for registering +the subsystem. This data structure includes a per-routine array that +specifies: +

    +
  • +The address of the server function that performs the work. +
  • +The address of the MIG-generated server-side marshalling stub, to be +used with mach_msg. +
  • +The argument signature (i.e. NDR-style argument format) of the +routine. +
+

+Upon successful completion, mach_subsystem_create returns, +via the subsys parameter, a port naming the registered subsystem. +

+Each port on which the server is to receive short-circuited RPC's (or +a mach_rpc call) must be associated with a registered subsystem, by +calling mach_port_allocate_subsystem. +

RETURN VALUES

+
+

+

KERN_INVALD_ADDRESS +
+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). +

+

KERN_INVALID_ARGUMENT +
+The port name specified by target_task is not a send right naming a task, +or the subsystem size is too small to be valid. +

+

KERN_INVALID_TASK +
+The target task is dead. +

+

KERN_RESOURCE_SHORTAGE +
+The kernel cannot allocate the subsystem due to insufficient available +memory. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate_subsystem, +thread_activation_create. 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 @@ -

mach_task_self

System Trap - Return a send right to the caller's task_self port.

SYNOPSIS

#include<mach/mach_traps.h>

mach_port_t   mach_task_self (void)

PARAMETERS

None.

DESCRIPTION

The mach_task_self function returns send rights to the task's kernel port.

NOTES

This function call is redefined in the mach_init.h file to return the caller's mach_task_self_ environment variable, which is cached on behalf of the caller's task at runtime. (The mach_init.h file is itself included via the mach.h file.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_set_special_port. \ No newline at end of file +

mach_task_self

+
+

+System Trap - Return a send right to the caller's task_self port. +

SYNOPSIS

+
+#include<mach/mach_traps.h>
+
+mach_port_t   mach_task_self (void)
+
+

PARAMETERS

+

+None. +

DESCRIPTION

+

+The mach_task_self function returns send rights to +the task's kernel port. +

NOTES

+

+This function call is redefined in the mach_init.h file +to return the caller's mach_task_self_ environment variable, +which is cached on behalf of the caller's task at runtime. +(The mach_init.h file is itself included via the +mach.h file. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_set_special_port. 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 @@ -

mach_thread_self

System Trap - Returns the thread self port.

SYNOPSIS

#include 

thread_port_t   mach_thread_self( void );

PARAMETERS

None.

DESCRIPTION

The mach_thread_self function returns send rights to the thread's own kernel port.

RETURN VALUES

[thread-self send right] Send rights to the thread's port.

RELATED INFORMATION

Functions: thread_info, thread_set_special_port. \ No newline at end of file +

mach_thread_self

+
+

+System Trap - Returns the thread self port. + +

SYNOPSIS

+

+#include +

+thread_port_t   mach_thread_self( void );
+
+

PARAMETERS

+

+None. +

DESCRIPTION

+

+The mach_thread_self function returns send rights +to the thread's own kernel port. +

RETURN VALUES

+

+[thread-self send right] Send rights to the thread's port. +

RELATED INFORMATION

+

+Functions: +thread_info, +thread_set_special_port. + 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 @@ -

mapped_tvalspec

Structure - Specifies the format the kernel uses to maintain a mapped clock's time.

SYNOPSIS

struct mapped_tvalspec
{
       tvalspec_t          mtv_time;
       unsigned int        mtv_csec;
};

typedef struct mapped_tvalspec mapped_tvalspec_t;

FIELDS

mtv_time
Clock time.

mtv_csec
A field used to synchronize with the kernel's setting of the time.

DESCRIPTION

The mapped_tvalspec structure defines the format of the current-time structure maintained by the kernel and visible through a mapped clock (clock_map_time). The data in this structure is updated at the clock's current resolution and contains the same tvalspec value that would be returned by clock_get_time.

NOTES

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: 

   tvalspec_t* ts;
   do
   {
              ts-> tv_sec = mtime -> mtv_time.tv_sec;
              ts  -> tv_nsec = mtime -> mtv_time.tv_nsec;
   } while (ts  -> tv_sec != mtime -> mtv_csec);

RELATED INFORMATION

Functions: clock_map_time, clock_get_time.

Data Structures: tvalspec. \ No newline at end of file +

mapped_tvalspec

+
+

+Structure - Specifies the format the kernel uses to maintain a mapped clock's time. +

SYNOPSIS

+
+struct mapped_tvalspec
+{
+       tvalspec_t          mtv_time;
+       unsigned int        mtv_csec;
+};
+
+typedef struct mapped_tvalspec mapped_tvalspec_t;
+
+

FIELDS

+
+
mtv_time +
+Clock time. +

+

mtv_csec +
+A field used to synchronize with the kernel's setting of the time. +
+

DESCRIPTION

+

+The mapped_tvalspec structure defines the format of the +current-time structure +maintained by the kernel and visible through a mapped clock +(clock_map_time). The data in this structure is updated at the +clock's current resolution and contains the same tvalspec value that +would be returned by clock_get_time. +

NOTES

+

+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: +

+

+   tvalspec_t* ts;
+   do
+   {
+              ts-> tv_sec = mtime -> mtv_time.tv_sec;
+              ts  -> tv_nsec = mtime -> mtv_time.tv_nsec;
+   } while (ts  -> tv_sec != mtime -> mtv_csec);
+
+

RELATED INFORMATION

+

+Functions: +clock_map_time, +clock_get_time. +

+Data Structures: +tvalspec. 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 @@ -

memory_object_attr_info

Structure - Specifies memory object's behavior attributes.

SYNOPSIS

struct  memory_object_attr_info
{
        memory_object_copy_strategy_t    copy_strategy;
        vm_offset_t                       cluster_size;
        boolean_t                            may_cache;
        boolean_t                            temporary;
};

typedef struct memory_object_attr_info* memory_object_attr_info_t;

FIELDS

copy_strategy
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:

MEMORY_OBJECT_COPY_NONE
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.

MEMORY_OBJECT_COPY_CALL
Call the memory manager when a copy operation is necessary.

MEMORY_OBJECT_COPY_DELAY
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.

MEMORY_OBJECT_COPY_TEMPORARY
All changes are made in memory and the memory manager does not need to see them.

MEMORY_OBJECT_COPY_SYMMETRIC
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.

cluster_size
The memory object's perferred cluster size (in bytes). This value may affect the number of pages transferred in a given paging operation.

may_cache
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.

temporary
If TRUE, when the last mapping to the object is released, the kernel destroys the object without returning any resident pages.

DESCRIPTION

The memory_object_attr_info structure defines behavior and performance relevant memory object attributes.

RELATED INFORMATION

Functions: memory_object_get_attributes, memory_object_change_attributes, vm_region, memory_object_synchronize, vm_set_default_memory_manager, vm_msync. \ No newline at end of file +

memory_object_attr_info

+
+

+Structure - Specifies memory object's behavior attributes. +

SYNOPSIS

+
+struct  memory_object_attr_info
+{
+        memory_object_copy_strategy_t    copy_strategy;
+        vm_offset_t                       cluster_size;
+        boolean_t                            may_cache;
+        boolean_t                            temporary;
+};
+
+typedef struct memory_object_attr_info* memory_object_attr_info_t;
+
+

FIELDS

+
+
copy_strategy +
+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: +
+

+

MEMORY_OBJECT_COPY_NONE +
+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. +

+

MEMORY_OBJECT_COPY_CALL +
+Call the memory manager when a copy operation is necessary. +

+

MEMORY_OBJECT_COPY_DELAY +
+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. +

+

MEMORY_OBJECT_COPY_TEMPORARY +
+All changes are made in memory and the memory manager does not need +to see them. +

+

MEMORY_OBJECT_COPY_SYMMETRIC +
+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. +
+

+

cluster_size +
+The memory object's perferred cluster size (in bytes). This value may affect +the number of pages transferred in a given paging operation. +

+

may_cache +
+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. +

+

temporary +
+If TRUE, when the last mapping to the object is released, +the kernel destroys the object without returning any resident pages. +
+

DESCRIPTION

+

+The memory_object_attr_info structure defines behavior and +performance relevant memory object attributes. +

RELATED INFORMATION

+

+Functions: +memory_object_get_attributes, +memory_object_change_attributes, +vm_region, +memory_object_synchronize, +vm_set_default_memory_manager, +vm_msync. 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 @@ -

memory_object_create

Function - Request that the default pager handle management requests on the specified memory object.

SYNOPSIS

kern_return_t   memory_object_create
                (memory_object_t                          pager,
                 memory_object_t              new_memory_object,
                 vm_size_t                      new_object_size,
                 memory_object_control_t            new_control,
                 vm_size_t                        new_page_size);


kern_return_t   seqnos_memory_object_create
                (memory_object_t                          pager,
                 mach_port_seqno_t                        seqno,
                 memory_object_t              new_memory_object,
                 vm_size_t                      new_object_size,
                 memory_object_control_t            new_control,
                 vm_size_t                        new_page_size);

PARAMETERS

pager
[in default-pager (receive) right] The default memory manager service port.

seqno
[in scalar] The sequence number of this message relative to the pager port.

new_memory_object
[in abstract-memory-object receive right] The port representing the new abstract memory object created by the kernel.

new_object_size
[in scalar] The expected size for the new object, in bytes.

new_control
[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.

new_page_size
[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.

DESCRIPTION

A memory_object_create 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.

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 memory_object_data_request calls from the kernel, the default memory manager must use memory_object_data_unavailable for any pages that have not been written previously.

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 memory_object_change_attributes call.

NOTES

The kernel requires memory objects to provide temporary backing storage for zero-filled memory created by vm_allocate 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 memory_object_create to pass the new memory object to the default memory manager, which provides the storage.

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 host_default_memory_manager call.

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.

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: default_pager_object_create, memory_object_data_initialize, memory_object_data_unavailable, memory_object_default_server, seqnos_memory_object_default_server. \ No newline at end of file +

memory_object_create

+
+

+Function - Request that the default pager handle management requests on the specified memory object. +

SYNOPSIS

+
+kern_return_t   memory_object_create
+                (memory_object_t                          pager,
+                 memory_object_t              new_memory_object,
+                 vm_size_t                      new_object_size,
+                 memory_object_control_t            new_control,
+                 vm_size_t                        new_page_size);
+
+
+kern_return_t   seqnos_memory_object_create
+                (memory_object_t                          pager,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_t              new_memory_object,
+                 vm_size_t                      new_object_size,
+                 memory_object_control_t            new_control,
+                 vm_size_t                        new_page_size);
+
+

PARAMETERS

+
+

+

pager +
+[in default-pager (receive) right] +The default memory manager service +port. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the pager +port. +

+

new_memory_object +
+[in abstract-memory-object receive right] +The port representing the +new abstract memory object created by the kernel. +

+

new_object_size +
+[in scalar] +The expected size for the new object, in bytes. +

+

new_control +
+[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. +

+

new_page_size +
+[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. +
+

DESCRIPTION

+

+A memory_object_create 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. +

+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 memory_object_data_request calls from the +kernel, the default +memory manager must use memory_object_data_unavailable +for any pages that have not been written previously. +

+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 memory_object_change_attributes call. +

NOTES

+

+The kernel requires memory objects to provide temporary backing storage for +zero-filled memory created by vm_allocate 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 memory_object_create +to pass the +new memory object to the default memory manager, which provides the storage. +

+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 host_default_memory_manager call. +

+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. +

+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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +default_pager_object_create, +memory_object_data_initialize, +memory_object_data_unavailable, +memory_object_default_server, +seqnos_memory_object_default_server. 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 @@ -

memory_object_data_error

Function - An error prevents the supply of previously requested data.

SYNOPSIS

kern_return_t   memory_object_data_error
                (memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                                 size,
                 kern_return_t                           reason);

PARAMETERS

memory_control
[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 memory_object_create call.

offset
[in scalar] The offset within the memory object, in bytes.

size
[in scalar] The number of bytes of data (starting at offset). The number must convert to an integral number of memory object pages.

reason
[in scalar] Reason for the error.

DESCRIPTION

The memory_object_data_error function indicates that the memory manager cannot provide the kernel with the data requested for the given region, specifying a reason for the error.

When the kernel issues a memory_object_data_request call, the memory manager can respond with a memory_object_data_error 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).

NOTES

If reason has a system code of err_kern, the kernel will substitute an error value of KERN_MEMORY_ERROR.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_data_request, memory_object_data_supply, memory_object_data_unavailable. \ No newline at end of file +

memory_object_data_error

+
+

+Function - An error prevents the supply of previously requested data. +

SYNOPSIS

+
+kern_return_t   memory_object_data_error
+                (memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                                 size,
+                 kern_return_t                           reason);
+
+

PARAMETERS

+
+

+

memory_control +
+[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 memory_object_create call. +

+

offset +
+[in scalar] +The offset within the memory object, in bytes. +

+

size +
+[in scalar] +The number of bytes of data (starting at offset). The number +must convert to an integral number of memory object pages. +

+

reason +
+[in scalar] +Reason for the error. +
+

DESCRIPTION

+

+The memory_object_data_error function indicates that +the memory manager +cannot provide the kernel with the data requested for the given region, +specifying a reason for the error. +

+When the kernel issues a memory_object_data_request call, the memory +manager can respond with a memory_object_data_error +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). +

NOTES

+

+If reason has a system code of err_kern, the kernel will substitute +an error value +of KERN_MEMORY_ERROR. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_data_request, +memory_object_data_supply, +memory_object_data_unavailable. 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 @@ -

memory_object_data_request

Server Interface - Request that memory manager page-in specified data.

SYNOPSIS

kern_return_t   memory_object_data_request
                (memory_object_t                  memory_object,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                               length,
                 vm_prot_t                       desired_access);


kern_return_t   seqnos_memory_object_data_request
                (memory_object_t                  memory_object,
                 mach_port_seqno_t                        seqno,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                               length,
                 vm_prot_t                       desired_access);

PARAMETERS

memory_object
[in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data.

seqno
[in scalar] The sequence number of this message relative to the abstract memory object port.

memory_control
[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.

offset
[in scalar] The offset within the memory object.

length
[in scalar] The number of bytes requested, starting at offset. The number converts to an integral number of virtual pages.

desired_access
[in scalar] The memory access modes to be allowed for the cached data. Possible values are obtained by or'ing together the following values:

VM_PROT_READ
Allows read access.

VM_PROT_WRITE
Allows write access.

VM_PROT_EXECUTE
Allows execute access.

DESCRIPTION

A memory_object_data_request function is called as the result of a kernel message requesting data from the specified memory object, for at least the access specified.

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 memory_object_init or memory_object_create call.

The memory manager is expected to use memory_object_data_supply 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 memory_object_data_error call. The memory manager can also use memory_object_data_unavailable to tell the kernel to supply zero-filled memory for the region.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_data_error, memory_object_data_supply, memory_object_data_unavailable, memory_object_server, seqnos_memory_object_server. \ No newline at end of file +

memory_object_data_request

+
+

+Server Interface - Request that memory manager page-in specified data. +

SYNOPSIS

+
+kern_return_t   memory_object_data_request
+                (memory_object_t                  memory_object,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                               length,
+                 vm_prot_t                       desired_access);
+
+
+kern_return_t   seqnos_memory_object_data_request
+                (memory_object_t                  memory_object,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                               length,
+                 vm_prot_t                       desired_access);
+
+

PARAMETERS

+
+

+

memory_object +
+[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the abstract +memory object port. +

+

memory_control +
+[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. +

+

offset +
+[in scalar] +The offset within the memory object. +

+

length +
+[in scalar] +The number of bytes requested, starting at offset. The +number converts to an integral number of virtual pages. +

+

desired_access +
+[in scalar] +The memory access modes to be allowed for the cached +data. Possible values are obtained by or'ing together the following +values: +
+

+

VM_PROT_READ +
+Allows read access. +

+

VM_PROT_WRITE +
+Allows write access. +

+

VM_PROT_EXECUTE +
+Allows execute access. +
+
+

DESCRIPTION

+

+A memory_object_data_request function is called as +the result of a kernel +message requesting data from the specified memory object, for at least the +access specified. +

+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 +memory_object_init or memory_object_create call. +

+The memory manager is expected to use memory_object_data_supply 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 memory_object_data_error call. The +memory manager can also +use memory_object_data_unavailable to tell the kernel +to supply zero-filled +memory for the region. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_data_error, +memory_object_data_supply, +memory_object_data_unavailable, +memory_object_server, +seqnos_memory_object_server. + 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 @@ -

memory_object_data_return

Server Interface - Return memory object data to the appropriate memory manager.

SYNOPSIS

kern_return_t   memory_object_data_return
                (memory_object_t                  memory_object,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 pointer_t                                 data,
                 boolean_t                                dirty,
                 boolean_t                          kernel_copy);


kern_return_t   seqnos_memory_object_data_return
                (memory_object_t                  memory_object,
                 mach_port_seqno_t                        seqno,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 pointer_t                                 data,
                 boolean_t                                dirty,
                 boolean_t                          kernel_copy);

PARAMETERS

memory_object
[in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data.

seqno
[in scalar] The sequence number of this message relative to the abstract memory object port.

memory_control
[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.

offset
[in scalar] The offset within the memory object.

data
[in pointer to dynamic array of bytes] The data that has been evicted from the physical memory cache.

dirty
[in scalar] If TRUE, the pages returned have been modified.

kernel_copy
[in scalar] If TRUE, the kernel has kept a copy of the page.

DESCRIPTION

A memory_object_data_return 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.

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 vm_deallocate to release the memory resources.

NOTES

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.

The kernel may re-request the returned data at any time following this message (including immediately).

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_data_supply, vm_deallocate, memory_object_synchronize, memory_object_server, seqnos_memory_object_server. \ No newline at end of file +

memory_object_data_return

+
+

+Server Interface - Return memory object data to the appropriate memory manager. +

SYNOPSIS

+
+kern_return_t   memory_object_data_return
+                (memory_object_t                  memory_object,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 pointer_t                                 data,
+                 boolean_t                                dirty,
+                 boolean_t                          kernel_copy);
+
+
+kern_return_t   seqnos_memory_object_data_return
+                (memory_object_t                  memory_object,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 pointer_t                                 data,
+                 boolean_t                                dirty,
+                 boolean_t                          kernel_copy);
+
+

PARAMETERS

+
+

+

memory_object +
+[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the abstract +memory object port. +

+

memory_control +
+[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. +

+

offset +
+[in scalar] +The offset within the memory object. +

+

data +
+[in pointer to dynamic array of bytes] +The data that has been evicted +from the physical memory cache. +

+

dirty +
+[in scalar] +If TRUE, the pages returned have been modified. +

+

kernel_copy +
+[in scalar] +If TRUE, the kernel has kept a copy of the page. +
+

DESCRIPTION

+

+A memory_object_data_return 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. +

+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 vm_deallocate +to release the +memory resources. +

NOTES

+

+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. +

+The kernel may re-request the returned data at any time following this message +(including immediately). +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_data_supply, +vm_deallocate, +memory_object_synchronize, +memory_object_server, +seqnos_memory_object_server. 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 @@ -

memory_object_data_supply

Function - Provide kernel with data previously requested by the kernel's Memory Management facility.

SYNOPSIS

kern_return_t   memory_object_data_supply
                (mem_object_control_port_t       memory_control,
                 vm_offset_t                             offset,
                 pointer_t                                 data,
                 mach_msg_type_number_t              data_count,
                 boolean_t                           deallocate,
                 vm_prot_t                           lock_value,
                 boolean_t                             precious,
                 mach_port_t                         reply_port);

PARAMETERS

memory_control
[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 memory_object_init or memory_object_create call.

offset
[in scalar] The offset within the memory object, in bytes.

data
[pointer to page aligned in array of bytes] The address of the data being provided to the kernel.

data_count
[in scalar] The amount of data to be provided. The number must be an integral number of memory object pages.

deallocate
[in scalar] If TRUE, 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.

lock_value
[in scalar] One or more forms of access not permitted for the specified data. Valid values are:

VM_PROT_NONE
Prohibits no access (that is, all forms of access are permitted).

VM_PROT_READ
Prohibits read access.

VM_PROT_WRITE
Prohibits write access.

VM_PROT_EXECUTE
Prohibits execute access.

VM_PROT_ALL
Prohibits all forms of access.

precious
[in scalar] If TRUE, 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.

reply_port
[in reply receive (to be converted to send) right] A port to which the kernel should send a memory_object_supply_completed to indicate the status of the accepted data. MACH_PORT_NULL is allowed. The reply message indicates which pages have been accepted.

DESCRIPTION

The memory_object_data_supply 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 memory_object_data_request call from the kernel.

NOTES

The kernel accepts only integral numbers of pages. It discards any partial pages without notification.

CAUTIONS

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 memory_object_lock_request) before proceeding. The kernel prohibits the overwriting of live data pages and will not accept pages it has not requested.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_data_error, memory_object_data_request, memory_object_data_unavailable, memory_object_lock_request, memory_object_supply_completed. \ No newline at end of file +

memory_object_data_supply

+
+

+Function - Provide kernel with data previously requested by the kernel's Memory Management facility. +

SYNOPSIS

+
+kern_return_t   memory_object_data_supply
+                (mem_object_control_port_t       memory_control,
+                 vm_offset_t                             offset,
+                 pointer_t                                 data,
+                 mach_msg_type_number_t              data_count,
+                 boolean_t                           deallocate,
+                 vm_prot_t                           lock_value,
+                 boolean_t                             precious,
+                 mach_port_t                         reply_port);
+
+

PARAMETERS

+
+
memory_control +
+[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 memory_object_init + or memory_object_create call. +

+

+

offset +
+[in scalar] +The offset within the memory object, in bytes. +

+

+

data +
+[pointer to page aligned in array of bytes] +The address of the data +being provided to the kernel. +

+

+

data_count +
+[in scalar] +The amount of data to be provided. The number must be an +integral number of memory object pages. +

+

+

deallocate +
+[in scalar] +If TRUE, 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. +

+

+

lock_value +
+[in scalar] +One or more forms of access not permitted for the specified +data. Valid values are: +
+

+

+

VM_PROT_NONE +
+Prohibits no access (that is, all forms of access are permitted). +

+

+

VM_PROT_READ +
+Prohibits read access. +

+

+

VM_PROT_WRITE +
+Prohibits write access. +

+

+

VM_PROT_EXECUTE +
+Prohibits execute access. +

+

+

VM_PROT_ALL +
+Prohibits all forms of access. +
+

+

+

precious +
+[in scalar] +If TRUE, 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. +

+

+

reply_port +
+[in reply receive (to be converted to send) right] +A port to which the +kernel should send a memory_object_supply_completed to indicate +the status of the accepted data. MACH_PORT_NULL is allowed. The +reply message indicates which pages have been accepted. +
+

DESCRIPTION

+

+The memory_object_data_supply 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 memory_object_data_request +call from the kernel. +

NOTES

+

+The kernel accepts only integral numbers of pages. It discards +any partial pages +without notification. +

CAUTIONS

+

+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 +memory_object_lock_request) before proceeding. The kernel prohibits the +overwriting of live data pages and will not accept pages it has not requested. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_data_error, +memory_object_data_request, +memory_object_data_unavailable, +memory_object_lock_request, +memory_object_supply_completed. 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 @@ -

memory_object_data_unlock

Server Interface - Request that the memory manager change current access permission on the specified memory object's data.

SYNOPSIS

kern_return_t   memory_object_data_unlock
                (memory_object_t                  memory_object,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                               length,
                 vm_prot_t                       desired_access);


kern_return_t   seqnos_memory_object_data_unlock
                (memory_object_t                  memory_object,
                 mach_port_seqno_t                        seqno,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                               length,
                 vm_prot_t                       desired_access);

PARAMETERS

memory_object
[in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data.

seqno
[in scalar] The sequence number of this message relative to the abstract memory object port.

memory_control
[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.

offset
[in scalar] The offset within the memory object.

length
[in scalar] The number of bytes to which the access applies, starting at offset. The number converts to an integral number of memory object pages.

desired_access
[in scalar] The memory access modes requested for the cached data. Possible values are obtained by or'ing together the following values:

VM_PROT_READ
Allows read access.

VM_PROT_WRITE
Allows write access.

VM_PROT_EXECUTE
Allows execute access.

DESCRIPTION

A memory_object_data_unlock 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 memory_object_lock_request call in response.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_lock_completed, memory_object_lock_request, memory_object_server, seqnos_memory_object_server. \ No newline at end of file +

memory_object_data_unlock

+
+

+Server Interface - Request that the memory manager change current access permission on the specified memory object's data. +

SYNOPSIS

+
+kern_return_t   memory_object_data_unlock
+                (memory_object_t                  memory_object,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                               length,
+                 vm_prot_t                       desired_access);
+
+
+kern_return_t   seqnos_memory_object_data_unlock
+                (memory_object_t                  memory_object,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                               length,
+                 vm_prot_t                       desired_access);
+
+

PARAMETERS

+
+

+

memory_object +
+[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the abstract +memory object port. +

+

memory_control +
+[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. +

+

offset +
+[in scalar] +The offset within the memory object. +

+

length +
+[in scalar] +The number of bytes to which the access applies, starting at +offset. The number converts to an integral number of memory object +pages. +

+

desired_access +
+[in scalar] +The memory access modes requested for the cached data. +Possible values are obtained by or'ing together the following values: +
+

+

VM_PROT_READ +
+Allows read access. +

+

VM_PROT_WRITE +
+Allows write access. +

+

VM_PROT_EXECUTE +
+Allows execute access. +
+
+

DESCRIPTION

+

+A memory_object_data_unlock 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 +memory_object_lock_request call in response. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_lock_completed, +memory_object_lock_request, +memory_object_server, +seqnos_memory_object_server. 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 @@ -

memory_object_destroy

Function - Shut down a memory object.

SYNOPSIS

kern_return_t   memory_object_destroy
                (memory_object_control_t         memory_control,
                 kern_return_t                           reason);

PARAMETERS

memory_control
[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 memory_object_init call.

reason
[in scalar] An error code indicating when the object must be destroyed.

DESCRIPTION

The memory_object_destroy 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 memory_object_terminate call to pass to the memory manager all rights to the memory object port and the memory control port.

To ensure that any modified cached data is returned before the object is terminated, the memory manager should call memory_object_lock_request with should_flush set and a lock value of VM_PROT_WRITE before it makes the memory_object_destroy call.

NOTES

The reason code is currently ignored by the kernel.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_lock_request, memory_object_terminate. \ No newline at end of file +

memory_object_destroy

+
+

+Function - Shut down a memory object. +

SYNOPSIS

+
+kern_return_t   memory_object_destroy
+                (memory_object_control_t         memory_control,
+                 kern_return_t                           reason);
+
+

PARAMETERS

+
+

+

memory_control +
+[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 memory_object_init call. +

+

reason +
+[in scalar] +An error code indicating when the object must be destroyed. +
+

DESCRIPTION

+

+The memory_object_destroy 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 memory_object_terminate call to pass to the memory +manager all rights to +the memory object port and the memory control port. +

+To ensure that any modified cached data is returned before the object is +terminated, the memory manager should call memory_object_lock_request +with +should_flush set and a +lock value of VM_PROT_WRITE before it makes the +memory_object_destroy call. +

NOTES

+

+The reason code is currently ignored by the kernel. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_lock_request, +memory_object_terminate. 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 @@ -

memory_object_init

Server Interface - Initializes a memory object.

SYNOPSIS

kern_return_t   memory_object_init
		(memory_object_t                memory_object,
		 memory_object_control_t       memory_control,
		 vm_size_t            memory_object_page_size);


kern_return_t   seqnos_memory_object_init
		(memory_object_t                memory_object,
		 mach_port_seqno_t                      seqno,
		 memory_object_control_t       memory_control,
		 vm_size_t            memory_object_page_size);

PARAMETERS

memory_object
[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.

seqno
[in scalar] The sequence number of this message relative to the abstract memory object port.

memory_control
[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.

memory_object_page_size
[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.

DESCRIPTION

A memory_object_init 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 memory_object_init 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.

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.

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.

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 memory_object_init call from each kernel, containing a unique set of control and name ports. Note that each kernel may also use a different page size.

RETURN VALUES

Any return value other than KERN_SUCCESS or MIG_NO_REPLYwill cause mach_msg_server to remove the memory cache control reference.

RELATED INFORMATION

Functions: memory_object_terminate. \ No newline at end of file +

memory_object_init

+
+

+Server Interface - Initializes a memory object. +

SYNOPSIS

+
+kern_return_t   memory_object_init
+		(memory_object_t                memory_object,
+		 memory_object_control_t       memory_control,
+		 vm_size_t            memory_object_page_size);
+
+
+kern_return_t   seqnos_memory_object_init
+		(memory_object_t                memory_object,
+		 mach_port_seqno_t                      seqno,
+		 memory_object_control_t       memory_control,
+		 vm_size_t            memory_object_page_size);
+
+

PARAMETERS

+
+
memory_object +
+[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. +

+

seqno +
+[in scalar] The sequence number of this message relative to the abstract memory object port. +

+

memory_control +
+[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. +

+

memory_object_page_size +
+[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. +
+

DESCRIPTION

+

+A memory_object_init 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 memory_object_init +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. +

+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. +

+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. +

+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 +memory_object_init call from each kernel, containing +a unique set of control and name ports. Note that each kernel may also +use a different page size. +

RETURN VALUES

+

+ +Any return value other than KERN_SUCCESS +or MIG_NO_REPLYwill cause +mach_msg_server to remove the memory cache control reference. +

RELATED INFORMATION

+

+Functions: +memory_object_terminate. 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 @@ -

memory_object_lock_request

Function - Restrict access to memory object data.

SYNOPSIS

kern_return_t   memory_object_lock_request
                (memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                                 size,
                 memory_object_return_t           should_return,
                 boolean_t                         should_flush,
                 vm_prot_t                           lock_value,
                 mach_port_t                         reply_port);

PARAMETERS

memory_control
[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 memory_object_init call.

offset
[in scalar] The offset within the memory object, in bytes.

size
[in scalar] The number of bytes of data (starting at offset) to be affected. The number must convert to an integral number of memory object pages.

should_return
[in scalar] Clean indicator. Values are:

MEMORY_OBJECT_RETURN_NONE
Don't return any pages. If should_flush is TRUE, pages will be discarded.

MEMORY_OBJECT_RETURN_DIRTY
Return only dirty (modified) pages. If should_flush is TRUE, precious pages will be discarded; otherwise, the kernel maintains responsibility for precious pages.

MEMORY_OBJECT_RETURN_ALL
Both dirty and precious pages are returned. If should_flush is FALSE, the kernel maintains responsibility for the precious pages.

MEMORY_OBJECT_RETURN_ANYTHING
Any resident pages are returned. If should_flush is TRUE, precious pages will be discarded; otherwise, the kernel maintains responsibility for precious pages.

should_flush
[in scalar] Flush indicator. If true, the kernel discards all pages within the range.

lock_value
[in scalar] One or more forms of access not permitted for the specified data. Valid values are:

VM_PROT_NO_CHANGE
Do not change the protection of any pages.

VM_PROT_NONE
Prohibits no access (that is, all forms of access are permitted).

VM_PROT_READ
Prohibits read access.

VM_PROT_WRITE
Prohibits write access.

VM_PROT_EXECUTE
Prohibits execute access.

VM_PROT_ALL
Prohibits all forms of access.

reply_port
[in reply receive (to be converted to send) right] The response port to be used by the kernel on a call to memory_object_lock_completed, or MACH_PORT_NULL if no response is required.

DESCRIPTION

The memory_object_lock_request function allows the memory manager to make the following requests of the kernel:

  • Clean the pages within the specified range by writing back all changed (that is, dirty) and precious pages. The kernel uses the memory_object_data_return call to write back the data. The should_return parameter must be set to non-zero.

  • Flush all cached data within the specified range. The kernel invalidates the range of data and revokes all uses of that data. The should_flush parameter must be set to true.

  • Alter access restrictions specified in the memory_object_data_supply call or a previous memory_object_lock_request call. The lock_value parameter must specify the new access restrictions. Note that this parameter can be used to unlock previously locked data.

Once the kernel performs all of the actions requested by this call, it issues a memory_object_lock_completed call using the reply_to port.

NOTES

The memory_object_lock_request 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.

When a running thread requires an access that is currently prohibited, the kernel issues a memory_object_data_unlock call specifying the access required. The memory manager can then use memory_object_lock_request to relax its access restrictions on the data.

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 memory_object_data_error.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_data_supply, memory_object_data_unlock, memory_object_lock_completed. \ No newline at end of file +

memory_object_lock_request

+
+

+Function - Restrict access to memory object data. +

SYNOPSIS

+
+kern_return_t   memory_object_lock_request
+                (memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_size_t                                 size,
+                 memory_object_return_t           should_return,
+                 boolean_t                         should_flush,
+                 vm_prot_t                           lock_value,
+                 mach_port_t                         reply_port);
+
+

PARAMETERS

+
+

+

memory_control +
+[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 memory_object_init call. +

+

offset +
+[in scalar] +The offset within the memory object, in bytes. +

+

size +
+[in scalar] +The number of bytes of data (starting at offset) to be +affected. The number must convert to an integral number of memory object +pages. +

+

should_return +
+[in scalar] +Clean indicator. Values are: +
+

+

MEMORY_OBJECT_RETURN_NONE +
+Don't return any pages. If should_flush is TRUE, pages will +be discarded. +

+

MEMORY_OBJECT_RETURN_DIRTY +
+Return only dirty (modified) pages. If should_flush is TRUE, +precious pages will be discarded; otherwise, the kernel +maintains responsibility for precious pages. +

+

MEMORY_OBJECT_RETURN_ALL +
+Both dirty and precious pages are returned. If should_flush is +FALSE, the kernel maintains responsibility for the precious +pages. +

+

MEMORY_OBJECT_RETURN_ANYTHING +
+Any resident pages are returned. If should_flush is TRUE, +precious pages will be discarded; otherwise, the kernel +maintains responsibility for precious pages. +
+

+

should_flush +
+[in scalar] +Flush indicator. If true, the kernel discards all pages within +the range. +

+

lock_value +
+[in scalar] +One or more forms of access not permitted for the specified +data. Valid values are: +
+

+

VM_PROT_NO_CHANGE +
+Do not change the protection of any pages. +

+

VM_PROT_NONE +
+Prohibits no access (that is, all forms of access are permitted). +

+

VM_PROT_READ +
+Prohibits read access. +

+

VM_PROT_WRITE +
+Prohibits write access. +

+

VM_PROT_EXECUTE +
+Prohibits execute access. +

+

VM_PROT_ALL +
+Prohibits all forms of access. +
+

+

reply_port +
+[in reply receive (to be converted to send) right] +The response port to +be used by the kernel on a call to memory_object_lock_completed, +or MACH_PORT_NULL if no response is required. +
+

DESCRIPTION

+

+The memory_object_lock_request function allows the memory manager to +make the following requests of the kernel: +

    +
  • +Clean the pages within the specified range by writing back all changed (that +is, dirty) and precious pages. The kernel uses the +memory_object_data_return call to write back the data. +The should_return parameter must be set to +non-zero. +

    +

  • +Flush all cached data within the specified range. The kernel invalidates the +range of data and revokes all uses of that data. The should_flush +parameter must be set to true. +

    +

  • +Alter access restrictions specified in the memory_object_data_supply +call +or a previous memory_object_lock_request call. The +lock_value parameter +must specify the new access restrictions. Note that this parameter can be +used to unlock previously locked data. +
+

+Once the kernel performs all of the actions requested by this +call, it issues a +memory_object_lock_completed call using the reply_to port. +

NOTES

+

+The memory_object_lock_request 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. +

+When a running thread requires an access that is currently prohibited, +the kernel +issues a memory_object_data_unlock call specifying +the access required. The +memory manager can then use memory_object_lock_request to relax its +access restrictions on the data. +

+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 +memory_object_data_error. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_data_supply, +memory_object_data_unlock, +memory_object_lock_completed. + 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 @@ -

memory_object_perf_info

Structure - Specifies a memory object's attributes with respect to performance.

SYNOPSIS

struct  memory_object_perf_info
{
        vm_offset_t      cluster_size;
        boolean_t    may_cache_object;
};

typedef struct memory_object_perf_info* memory_object_perf_info_t;

FIELDS

cluster_size
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.

may_cache_object
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.

DESCRIPTION

The memory_object_perf_info structure defines a memory object's character with respect to performance.

NOTES

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.

RELATED INFORMATION

Functions: memory_object_get_attributes, memory_object_change_attributes, vm_region, memory_object_synchronize, vm_set_default_memory_manager, vm_msync.

Structures: memory_object_attr_info. \ No newline at end of file +

memory_object_perf_info

+
+

+Structure - Specifies a memory object's attributes with respect to performance. +

SYNOPSIS

+
+struct  memory_object_perf_info
+{
+        vm_offset_t      cluster_size;
+        boolean_t    may_cache_object;
+};
+
+typedef struct memory_object_perf_info* memory_object_perf_info_t;
+
+

FIELDS

+
+
cluster_size +
+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. +

+

may_cache_object +
+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. +
+

DESCRIPTION

+

+The memory_object_perf_info structure +defines a memory object's character with respect to performance. +

NOTES

+

+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. +

RELATED INFORMATION

+

+Functions: +memory_object_get_attributes, +memory_object_change_attributes, +vm_region, +memory_object_synchronize, +vm_set_default_memory_manager, +vm_msync. +

+Structures: +memory_object_attr_info. 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 @@ -

memory_object_server

Function - Handle kernel operation request aimed at a given memory manager.

SYNOPSIS

boolean_t	memory_object_server
		(mach_msg_header_t	request_msg,
		mach_msg_header_t	reply_ms);

PARAMETERS

in_msg
[pointer to in structure] The memory manager message received from the kernel.

out_msg
[out structure] A reply message. No messages to a memory manager expect a direct reply, so this field is not used.

DESCRIPTION

The memory_object_server function is the MIG generated server handling function to handle messages from the kernel targeted to a memory manager.

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 memory_object_server function performs all necessary argument handling for a kernel message and calls one of the memory manager functions to interpret the message.

RETURN VALUES

TRUE
The message was handled and the appropriate function was called.

FALSE
The message did not apply to this memory management interface and no other action was taken.

RELATED INFORMATION

Functions: memory_object_default_server, memory_object_data_request, memory_object_data_return, memory_object_data_unlock, memory_object_lock_completed, memory_object_change_completed, memory_object_supply_completed, memory_object_terminate, memory_object_synchronize, seqnos_memory_object_server. \ No newline at end of file +

memory_object_server

+
+

+Function - Handle kernel operation request aimed at a given memory manager. +

SYNOPSIS

+
+boolean_t	memory_object_server
+		(mach_msg_header_t	request_msg,
+		mach_msg_header_t	reply_ms);
+
+

PARAMETERS

+
+

+

in_msg +
+[pointer to in structure] +The memory manager message received from +the kernel. +

+

out_msg +
+[out structure] +A reply message. No messages to a memory manager +expect a direct reply, so this field is not used. +
+

DESCRIPTION

+

+The memory_object_server function is the MIG generated +server handling +function to handle messages from the kernel targeted to a memory manager. +

+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 +memory_object_server function performs all necessary +argument handling for +a kernel message and calls one of the memory manager functions to interpret +the message. +

RETURN VALUES

+
+

+

TRUE +
+The message was handled and the appropriate function was called. +

+

FALSE +
+The message did not apply to this memory management interface and +no other action was taken. +
+

RELATED INFORMATION

+

+Functions: +memory_object_default_server, +memory_object_data_request, +memory_object_data_return, +memory_object_data_unlock, +memory_object_lock_completed, +memory_object_change_completed, +memory_object_supply_completed, +memory_object_terminate, +memory_object_synchronize, +seqnos_memory_object_server. 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 @@ -

memory_object_synchronize

Server Interface - Forward a client's request to synchronize data with its image in backing store.

SYNOPSIS

kern_return_t   memory_object_synchronize
                (memory_object_t                  memory_object,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_offset_t                             length,
                 memory_object                       sync_flags);


kern_return_t   seqnos_memory_object_synchronize
                (memory_object_t                  memory_object,
                 mach_port_seqno_t                        seqno,
                 memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_offset_t                             length,
                 memory_object                       sync_flags);

PARAMETERS

memory_object
[in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data.

seqno
[in scalar] The sequence number of this message relative to the abstract memory object port.

memory_control
[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.

offset
[in scalar] The offset within the memory object.

length
[in scalar] The number of bytes cleaned or flushed, starting at offset. The number converts to an integral number of virtual pages.

sync_flags
[in scalar] The bit-wise OR of flags affecting the synchronization.

VM_SYNC_INVALIDATE
Flushes pages in the range. Only precious pages are returned to the memory manager.

VM_SYNC_SYNCHRONOUS
Writes dirty and precious pages back to the memory manager, waits for pages to reach backing storage.

VM_SYNC_ASYNCHRONOUS
Writes dirty and precious pages back to the memory manager, returns without waiting for pages to reach backing storage.

DESCRIPTION

A memory_object_synchronize 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 memory_object_data_return messages cleaning or flushing the specified range.

Depending on the client's supplied sync_flags, the manager waits for the pages to reach the desired state and then replies with memory_object_synchronize_completed at which time the client returns from its vm_msync call. Multiple synchronize requests may be outstanding at a time but they will not overlap.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: vm_msync, memory_object_synchronize_completed, memory_object_data_return, memory_object_server, seqnos_memory_object_server. \ No newline at end of file +

memory_object_synchronize

+
+

+Server Interface - Forward a client's request to synchronize data with its image in backing store. +

SYNOPSIS

+
+kern_return_t   memory_object_synchronize
+                (memory_object_t                  memory_object,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_offset_t                             length,
+                 memory_object                       sync_flags);
+
+
+kern_return_t   seqnos_memory_object_synchronize
+                (memory_object_t                  memory_object,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_control_t         memory_control,
+                 vm_offset_t                             offset,
+                 vm_offset_t                             length,
+                 memory_object                       sync_flags);
+
+

PARAMETERS

+
+

+

memory_object +
+[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the abstract +memory object port. +

+

memory_control +
+[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. +

+

offset +
+[in scalar] +The offset within the memory object. +

+

length +
+[in scalar] +The number of bytes cleaned or flushed, starting at offset. +The number converts to an integral number of virtual pages. +

+

sync_flags +
+[in scalar] +The bit-wise OR of flags affecting the synchronization. +
+

+

VM_SYNC_INVALIDATE +
+Flushes pages in the range. Only precious pages are returned +to the memory manager. +

+

VM_SYNC_SYNCHRONOUS +
+Writes dirty and precious pages back to the memory manager, +waits for pages to reach backing storage. +

+

VM_SYNC_ASYNCHRONOUS +
+Writes dirty and precious pages back to the memory manager, +returns without waiting for pages to reach backing storage. +
+
+

DESCRIPTION

+

+A memory_object_synchronize 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 memory_object_data_return messages cleaning +or flushing the +specified range. +

+Depending on the client's supplied sync_flags, the manager waits +for the pages +to reach the desired state and then replies with +memory_object_synchronize_completed at which time the +client returns from its vm_msync call. Multiple +synchronize requests may be outstanding at a time but they will not overlap. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +vm_msync, +memory_object_synchronize_completed, +memory_object_data_return, +memory_object_server, +seqnos_memory_object_server. 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 @@ -

memory_object_terminate

Server Interface - Relinquish access to a memory object.

SYNOPSIS

kern_return_t   memory_object_terminate
                (memory_object_t                  memory_object,
                 memory_object_control_t         memory_control);



kern_return_t   seqnos_memory_object_terminate
                (memory_object_t                  memory_object,
                 mach_port_seqno_t                        seqno,
                 memory_object_control_t         memory_control);

PARAMETERS

memory_object
[in abstract-memory-object (receive) right] The abstract memory object port that represents the memory object data.

seqno
[in scalar] The sequence number of this message relative to the abstract memory object port.

memory_control
[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.

DESCRIPTION

A memory_object_terminate 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.

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_destroy, mach_port_deallocate, memory_object_server, seqnos_memory_object_server. \ No newline at end of file +

memory_object_terminate

+
+

+Server Interface - Relinquish access to a memory object. +

SYNOPSIS

+
+kern_return_t   memory_object_terminate
+                (memory_object_t                  memory_object,
+                 memory_object_control_t         memory_control);
+
+
+
+kern_return_t   seqnos_memory_object_terminate
+                (memory_object_t                  memory_object,
+                 mach_port_seqno_t                        seqno,
+                 memory_object_control_t         memory_control);
+
+

PARAMETERS

+
+

+

memory_object +
+[in abstract-memory-object (receive) right] +The abstract memory +object port that represents the memory object data. +

+

seqno +
+[in scalar] +The sequence number of this message relative to the abstract +memory object port. +

+

memory_control +
+[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. +
+

DESCRIPTION

+

+A memory_object_terminate 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. +

+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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +memory_object_destroy, +mach_port_deallocate, +memory_object_server, +seqnos_memory_object_server. 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 @@ -

norma_get_special_port

Function - Acquire a send right for a specified node-specific special port.

SYNOPSIS

kern_return_t   norma_get_special_port
                (host_priv_t                          host_priv,
                 int                                       node,
                 int                                 which_port,
                 mach_port_t                       special_port);

Macro forms:


#include<mach/norma_special_ports.h>

kern_return_t   norma_get_device_port
                (host_priv_t                          host_priv,
                 int                                       node,
                 mach_port_t                       special_port);

kern_return_t   norma_get_host_port
                (host_priv_t                          host_priv,
                 int                                       node,
                 mach_port_t                       special_port);

kern_return_t   norma_get_host_priv_port
                (host_priv_t                          host_priv,
                 int                                       node,
                 mach_port_t                       special_port);

kern_return_t   norma_get_nameserver_port
                (host_priv_t                          host_priv,
                 int                                       node,
                 mach_port_t                       special_port);

PARAMETERS

host_priv
[in host-control send right] The control port for the host for which to return the special port's send right.

node
[in scalar] The index of the node for which the port is desired.

which_port
[in scalar] The index of the special port for which the send right is requested. Valid values are:

NORMA_DEVICE_PORT
[device-master send right] The device master port for the node.

NORMA_HOST_PORT
[host-name send right] The host name port for the node.

NORMA_HOST_PRIV_PORT
[host-control send right] The host control port for the node.

NORMA_NAMESERVER_PORT
[name-server send right] The registered name server port for the node.

special_port
[out norma-special send right] The returned value for the port.

DESCRIPTION

The norma_get_special_port function returns a send right for a special port belonging to node on host_priv.

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_host_self, norma_get_special_port, bootstrap_ports. \ No newline at end of file +

norma_get_special_port

+
+

+Function - Acquire a send right for a specified node-specific special port. +

SYNOPSIS

+
+kern_return_t   norma_get_special_port
+                (host_priv_t                          host_priv,
+                 int                                       node,
+                 int                                 which_port,
+                 mach_port_t                       special_port);
+
+
+

Macro forms:

+
+
+#include<mach/norma_special_ports.h>
+
+kern_return_t   norma_get_device_port
+                (host_priv_t                          host_priv,
+                 int                                       node,
+                 mach_port_t                       special_port);
+
+kern_return_t   norma_get_host_port
+                (host_priv_t                          host_priv,
+                 int                                       node,
+                 mach_port_t                       special_port);
+
+kern_return_t   norma_get_host_priv_port
+                (host_priv_t                          host_priv,
+                 int                                       node,
+                 mach_port_t                       special_port);
+
+kern_return_t   norma_get_nameserver_port
+                (host_priv_t                          host_priv,
+                 int                                       node,
+                 mach_port_t                       special_port);
+
+

PARAMETERS

+
+
host_priv +
+[in host-control send right] +The control port for the host for which to +return the special port's send right. +

+

node +
+[in scalar] +The index of the node for which the port is desired. +

+

which_port +
+[in scalar] +The index of the special port for which the send right is +requested. Valid values are: +
+

+

NORMA_DEVICE_PORT +
+[device-master send right] The device master port for the +node. +

+

NORMA_HOST_PORT +
+[host-name send right] The host name port for the node. +

+

NORMA_HOST_PRIV_PORT +
+[host-control send right] The host control port for the node. +

+

NORMA_NAMESERVER_PORT +
+[name-server send right] The registered name server port for +the node. +
+

+

special_port +
+[out norma-special send right] +The returned value for the port. +
+

DESCRIPTION

+

+The norma_get_special_port function returns a send +right for a special port belonging to node on host_priv. +

+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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_host_self, +norma_get_special_port, +bootstrap_ports. 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 @@ -

norma_node_self

Function - Return the node index of the current host.

SYNOPSIS

kern_return_t   norma_node_self
                (host_t                                    host,
                 int                                        int);

PARAMETERS

host
[in host send-right] Name of the host.

node
[out scalar] Node index of the host.

DESCRIPTION

The norma_node_self function returns the node index of the current host.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: norma_task_create, norma_task_clone, \ No newline at end of file +

norma_node_self

+
+

+Function - Return the node index of the current host. +

SYNOPSIS

+
+kern_return_t   norma_node_self
+                (host_t                                    host,
+                 int                                        int);
+
+

PARAMETERS

+
+

+

host +
+[in host send-right] Name of the host. +

+

node +
+[out scalar] Node index of the host. +
+

DESCRIPTION

+

+The norma_node_self function returns the node index of the current host. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +norma_task_create, +norma_task_clone, 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 @@ -

norma_port_location_hint

Function - Guess a port's current location.

SYNOPSIS

kern_return_t   norma_port_location_hint
                (task_t                                    task,
                 mach_port_t                               name,
                 int                                       node);

PARAMETERS

task
[in task send right] Task containing the right to locate

name
[in scalar] Name of the right to locate

node
[out scalar] Port location hint

DESCRIPTION

The norma_port_location_hint function returns the best guess of name'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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: norma_task_create. \ No newline at end of file +

norma_port_location_hint

+
+

+Function - Guess a port's current location. +

SYNOPSIS

+
+kern_return_t   norma_port_location_hint
+                (task_t                                    task,
+                 mach_port_t                               name,
+                 int                                       node);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +Task containing the right to locate +

+

name +
+[in scalar] +Name of the right to locate +

+

node +
+[out scalar] +Port location hint +
+

DESCRIPTION

+

+The norma_port_location_hint function returns the best +guess of name'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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +norma_task_create. 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 @@ -

norma_set_special_port

Function - Set node-specific special port.

SYNOPSIS

kern_return_t   norma_set_special_port
                (host_priv_t                          host_priv,
                 int                                 which_port,
                 mach_port_t                       special_port);

Macro forms:


#include<mach/norma_special_ports.h>

kern_return_t   norma_set_device_port
                (host_priv_t                          host_priv,
                 mach_port_t                       special_port);

kern_return_t   norma_set_host_port
                (host_priv_t                          host_priv,
                 mach_port_t                       special_port);

kern_return_t   norma_set_host_priv_port
                (host_priv_t                          host_priv,
                 int                                       node,
                 mach_port_t                       special_port);

kern_return_t   norma_set_nameserver_port
                (host_priv_t                          host_priv,
                 mach_port_t                       special_port);

PARAMETERS

host_priv
[in host-control send right] The host for which to set the special port. Currently, this must be the per-node host control port.

node
[in scalar] The index of the node for which the port is to be set.

which_port
[in scalar] The index of the special port to be set. Valid values are:

NORMA_DEVICE_PORT
[device-master send right] The device master port for the node.

NORMA_HOST_PORT
[host-name send right] The host name port for the node.

NORMA_HOST_PRIV_PORT
[host-control send right] The host control port for the node.

NORMA_NAMESERVER_PORT
[name-server send right] The registered name server port for the node.

special_port
[in norma-special send right] Send right to the new special port.

DESCRIPTION

The norma_set_special_port function sets the special port belonging to node on host_priv.

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_host_self, norma_get_special_port. \ No newline at end of file +

norma_set_special_port

+
+

+Function - Set node-specific special port. +

SYNOPSIS

+
+kern_return_t   norma_set_special_port
+                (host_priv_t                          host_priv,
+                 int                                 which_port,
+                 mach_port_t                       special_port);
+
+
+

Macro forms:

+
+
+#include<mach/norma_special_ports.h>
+
+kern_return_t   norma_set_device_port
+                (host_priv_t                          host_priv,
+                 mach_port_t                       special_port);
+
+kern_return_t   norma_set_host_port
+                (host_priv_t                          host_priv,
+                 mach_port_t                       special_port);
+
+kern_return_t   norma_set_host_priv_port
+                (host_priv_t                          host_priv,
+                 int                                       node,
+                 mach_port_t                       special_port);
+
+kern_return_t   norma_set_nameserver_port
+                (host_priv_t                          host_priv,
+                 mach_port_t                       special_port);
+
+ +

PARAMETERS

+
+
host_priv +
+[in host-control send right] +The host for which to set the special port. +Currently, this must be the per-node host control port. +

+

node +
+[in scalar] +The index of the node for which the port is to be set. +

+

which_port +
+[in scalar] +The index of the special port to be set. Valid values are: +
+

+

NORMA_DEVICE_PORT +
+[device-master send right] The device master port for the +node. +

+

NORMA_HOST_PORT +
+[host-name send right] The host name port for the node. +

+

NORMA_HOST_PRIV_PORT +
+[host-control send right] The host control port for the node. +

+

NORMA_NAMESERVER_PORT +
+[name-server send right] The registered name server port for +the node. +
+

+

special_port +
+[in norma-special send right] +Send right to the new special port. +
+

DESCRIPTION

+

+The norma_set_special_port function sets the special +port belonging to node on host_priv. +

+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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_host_self, +norma_get_special_port. 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 @@ -

norma_task_clone

Function - Create a remote task that shares access to parent task's memory regardless of inheritance attributes.

SYNOPSIS

kern_return_t   norma_task_clone
                (task_t                             parent_task,
                 boolean_t                       inherit_memory,
                 int                                 child_node,
                 task_t                              child_task);

PARAMETERS

parent_task
[in task send right] The port for the task from which to draw the child task's port rights, resource limits, and address space.

inherit_memory
[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.

child_node
[in scalar] The node index of the node on which to create the child.

child_task
[out task send right] The kernel-assigned port name for the new task.

DESCRIPTION

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.

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.

NOTES

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create, norma_task_create. \ No newline at end of file +

norma_task_clone

+
+

+Function - Create a remote task that shares access to parent task's memory regardless of inheritance attributes. +

SYNOPSIS

+
+kern_return_t   norma_task_clone
+                (task_t                             parent_task,
+                 boolean_t                       inherit_memory,
+                 int                                 child_node,
+                 task_t                              child_task);
+
+

PARAMETERS

+
+

+

parent_task +
+[in task send right] +The port for the task from which to draw the child +task's port rights, resource limits, and address space. +

+

inherit_memory +
+[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. +

+

child_node +
+[in scalar] +The node index of the node on which to create the child. +

+

child_task +
+[out task send right] +The kernel-assigned port name for the new task. +
+

DESCRIPTION

+

+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. +

+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. +

NOTES

+

+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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_create, +norma_task_create. 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 @@ -

norma_task_create

Function - Create a remote task using task_create semantics.

SYNOPSIS

kern_return_t   norma_task_create
                (task_t                             parent_task,
                 boolean_t                       inherit_memory,
                 int                                 child_node,
                 task_t                              child_task);

PARAMETERS

parent_task
[in task send right] The port for the task from which to draw the child task's port rights, resource limits, and address space.

inherit_memory
[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.

child_node
[in scalar] The node index of the node on which to create the child.

child_task
[out task send right] The kernel-assigned port name for the new task.

DESCRIPTION

The norma_task_create function creates 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 or copied parts of the parent's address space (see vm_inherit). The child task initially contains no threads.

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create, norma_task_clone. \ No newline at end of file +

norma_task_create

+
+

+Function - Create a remote task using task_create semantics. +

SYNOPSIS

+
+kern_return_t   norma_task_create
+                (task_t                             parent_task,
+                 boolean_t                       inherit_memory,
+                 int                                 child_node,
+                 task_t                              child_task);
+
+

PARAMETERS

+
+

+

parent_task +
+[in task send right] +The port for the task from which to draw the child +task's port rights, resource limits, and address space. +

+

inherit_memory +
+[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. +

+

child_node +
+[in scalar] +The node index of the node on which to create the child. +

+

child_task +
+[out task send right] +The kernel-assigned port name for the new task. +
+

DESCRIPTION

+

+The norma_task_create function creates 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 or copied parts of the parent's address space (see +vm_inherit). The child task initially contains no threads. +

+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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_create, +norma_task_clone. 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 @@ -

norma_task_teleport

Function - "Clone" a task on a specified node.

SYNOPSIS

kern_return_t   norma_task_teleport
                (task_t                             parent_task,
                 boolean_t                       inherit_memory,
                 int                                 child_node,
                 task_t                              child_task);

PARAMETERS

parent_task
[in task send right] The port for the task from which to draw the child task's port rights, resource limits, and address space.

inherit_memory
[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.

child_node
[in scalar] The node index of the node on which to create the child.

child_task
[out task send right] The kernel-assigned port name for the new task.

DESCRIPTION

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.

NOTES

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: norma_task_clone, task_create, norma_task_create, \ No newline at end of file +

norma_task_teleport

+
+

+Function - "Clone" a task on a specified node. +

SYNOPSIS

+
+kern_return_t   norma_task_teleport
+                (task_t                             parent_task,
+                 boolean_t                       inherit_memory,
+                 int                                 child_node,
+                 task_t                              child_task);
+
+

PARAMETERS

+
+

+

parent_task +
+[in task send right] The port for the task from which to draw the child +task's port rights, resource limits, and address space. +

+

inherit_memory +
+[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. +

+

child_node +
+[in scalar] The node index of the node on which to create the child. +

+

child_task +
+[out task send right] The kernel-assigned port name for the new task. +
+

DESCRIPTION

+

+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. +

NOTES

+

+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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +norma_task_clone, +task_create, +norma_task_create, 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 @@ -

notify_server

Function - Handle the next kernel-generated IPC notification.

SYNOPSIS

boolean_t	notify_server
		(mach_msg_header_t	request_msg,
		mach_msg_header_t	reply_ms);

PARAMETERS

in_msg
[pointer to in structure] The notification message received from the kernel.

out_msg
[out structure] Not used.

DESCRIPTION

The notify_server 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 mach_msg or mach_port_request_notification call. The notify_server function performs all necessary argument handling for this kernel message and calls the appropriate handling function. These functions must be supplied by the caller.

RETURN VALUES

TRUE
The message was handled and the appropriate function was called.

FALSE
The message did not apply to the notification mechanism and no other action was taken.

RELATED INFORMATION

Functions: seqnos_notify_server, do_mach_notify_dead_name, do_mach_notify_no_senders, do_mach_notify_port_deleted, do_mach_notify_send_once. \ No newline at end of file +

notify_server

+
+

+Function - Handle the next kernel-generated IPC notification. +

SYNOPSIS

+
+boolean_t	notify_server
+		(mach_msg_header_t	request_msg,
+		mach_msg_header_t	reply_ms);
+
+

PARAMETERS

+
+

+

in_msg +
+[pointer to in structure] +The notification message received from the +kernel. +

+

out_msg +
+[out structure] +Not used. +
+

DESCRIPTION

+

+The notify_server 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 mach_msg +or mach_port_request_notification call. The notify_server +function performs all necessary +argument handling for this kernel message and calls the appropriate handling +function. These functions must be supplied by the caller. +

RETURN VALUES

+
+

+

TRUE +
+The message was handled and the appropriate function was called. +

+

FALSE +
+The message did not apply to the notification mechanism and no other +action was taken. +
+

RELATED INFORMATION

+

+Functions: +seqnos_notify_server, +do_mach_notify_dead_name, +do_mach_notify_no_senders, +do_mach_notify_port_deleted, +do_mach_notify_send_once. 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 @@ -

policy_fifo_info

Structure - Specifies information associated with the system's First-In-First-Out scheduling policy.

SYNOPSIS

struct policy_fifo_limit
{
       int                    max_priority;
};

struct policy_fifo_base
{
       int                  base_priority;
};

struct policy_fifo_info
{
       int                   max_priority;
       int                  base_priority;
       boolean_t                depressed;
       int               depress_priority;
};

FIELDS

max_priority
Maximum scheduling priority

base_priority
Scheduling priority

depressed
True if scheduling priority is depressed

depress_priority
Scheduling priority from which depressed

DESCRIPTION

The policy_fifo_info structure defines the first-in-first-out scheduling policy information. FIFO threads have two priorities associated with them by the system:

  • 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.

  • 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.

RELATED INFORMATION

Functions: thread_info, task_info, processor_set_info, processor_set_policy_control, processor_set_policy_disable, processor_set_policy_enable, task_policy, thread_policy, thread_set_policy.

Data Structures: policy_rr_info, policy_timeshare_info. \ No newline at end of file +

policy_fifo_info

+
+

+Structure - Specifies information associated with the system's First-In-First-Out scheduling policy. +

SYNOPSIS

+
+struct policy_fifo_limit
+{
+       int                    max_priority;
+};
+
+struct policy_fifo_base
+{
+       int                  base_priority;
+};
+
+struct policy_fifo_info
+{
+       int                   max_priority;
+       int                  base_priority;
+       boolean_t                depressed;
+       int               depress_priority;
+};
+
+

FIELDS

+
+
max_priority +
+Maximum scheduling priority +

+

base_priority +
+Scheduling priority +

+

depressed +
+True if scheduling priority is depressed +

+

depress_priority +
+Scheduling priority from which depressed +
+

DESCRIPTION

+

+The policy_fifo_info structure defines the first-in-first-out +scheduling policy information. +FIFO threads have two priorities associated with them by the system: +

    +

    +

  • +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. +

    +

  • +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. +
+

RELATED INFORMATION

+

+Functions: +thread_info, +task_info, +processor_set_info, +processor_set_policy_control, +processor_set_policy_disable, +processor_set_policy_enable, +task_policy, +thread_policy, +thread_set_policy. +

+Data Structures: +policy_rr_info, +policy_timeshare_info. 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 @@ -

policy_rr_info

Structure - Specifies information associated with the system's Round Robin scheduling policy.

SYNOPSIS

struct policy_rr_limit
{
       int          max_priority;
};

struct policy_rr_base
{
       int         base_priority;
       int               quantum;
};

struct policy_rr_info
{
       int          max_priority;
       int         base_priority;
       int               quantum;
       boolean_t       depressed;
       int      depress_priority;
};

FIELDS

max_priority
Maximum scheduling priority

base_priority
Scheduling priority

quantum
Scheduling quantum (in milliseconds)

depressed
True if scheduling priority is depressed

depress_priority
Scheduling priority from which depressed

DESCRIPTION

The policy_rr_info structure defines the round-robin scheduling policy information. Round-robin threads have two priorities associated with them by the system:

  • 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.

  • 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.

RELATED INFORMATION

Functions: thread_info, task_info, processor_set_info, processor_set_policy_control, processor_set_policy_disable, processor_set_policy_enable, task_policy, thread_policy, thread_set_policy.

Data Structures: policy_fifo_info, policy_timeshare_info. \ No newline at end of file +

policy_rr_info

+
+

+Structure - Specifies information associated with the system's Round Robin scheduling policy. +

SYNOPSIS

+
+struct policy_rr_limit
+{
+       int          max_priority;
+};
+
+struct policy_rr_base
+{
+       int         base_priority;
+       int               quantum;
+};
+
+struct policy_rr_info
+{
+       int          max_priority;
+       int         base_priority;
+       int               quantum;
+       boolean_t       depressed;
+       int      depress_priority;
+};
+
+

FIELDS

+
+
max_priority +
+Maximum scheduling priority +

+

base_priority +
+Scheduling priority +

+

quantum +
+Scheduling quantum (in milliseconds) +

+

depressed +
+True if scheduling priority is depressed +

+

depress_priority +
+Scheduling priority from which depressed +
+

DESCRIPTION

+

+The policy_rr_info structure defines the round-robin +scheduling policy information. +Round-robin threads have two priorities associated with them by the system: +

    +

    +

  • +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. +

    +

  • +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. +
+

RELATED INFORMATION

+

+Functions: +thread_info, +task_info, +processor_set_info, +processor_set_policy_control, +processor_set_policy_disable, +processor_set_policy_enable, +task_policy, +thread_policy, +thread_set_policy. +

+Data Structures: +policy_fifo_info, +policy_timeshare_info. 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 @@ -

policy_timeshare_info

Structure - Specifies information associated with the system's Timeshare scheduling policy.

SYNOPSIS

struct policy_timeshare_limit
{
       int            max_priority;
};

struct policy_timeshare_base
{
       int           base_priority;
};

struct policy_timeshare_info
{
       int            max_priority;
       int           base_priority;
       int            cur_priority;
       boolean_t         depressed;
       int        depress_priority;
};

FIELDS

max_priority
Maximum scheduling priority.

base_priority
Base scheduling priority.

cur_priority
Current scheduling priority.

depressed
True if scheduling priority is depressed.

depress_priority
Scheduling priority from which depressed.

DESCRIPTION

The policy_timeshare_info structure defines the timeshare scheduling policy information. Timeshare threads have three priorities associated with them by the system:

  • 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.

  • 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.

  • 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).

RELATED INFORMATION

Functions: thread_info, task_info, processor_set_info, processor_set_policy_control, processor_set_policy_disable, processor_set_policy_enable, task_policy, thread_policy, thread_set_policy.

Data Structures: policy_fifo_info, policy_rr_info. \ No newline at end of file +

policy_timeshare_info

+
+

+Structure - Specifies information associated with the system's Timeshare scheduling policy. +

SYNOPSIS

+
+struct policy_timeshare_limit
+{
+       int            max_priority;
+};
+
+struct policy_timeshare_base
+{
+       int           base_priority;
+};
+
+struct policy_timeshare_info
+{
+       int            max_priority;
+       int           base_priority;
+       int            cur_priority;
+       boolean_t         depressed;
+       int        depress_priority;
+};
+
+

FIELDS

+
+
max_priority +
+Maximum scheduling priority. +

+

base_priority +
+Base scheduling priority. +

+

cur_priority +
+Current scheduling priority. +

+

depressed +
+True if scheduling priority is depressed. +

+

depress_priority +
+Scheduling priority from which depressed. +
+

DESCRIPTION

+

+The policy_timeshare_info structure defines the timeshare +scheduling policy +information. +Timeshare threads have three priorities associated with them by the system: +

    +

    +

  • +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. +

    +

  • +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. +

    +

  • +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). +
+

RELATED INFORMATION

+

+Functions: +thread_info, +task_info, +processor_set_info, +processor_set_policy_control, +processor_set_policy_disable, +processor_set_policy_enable, +task_policy, +thread_policy, +thread_set_policy. +

+Data Structures: +policy_fifo_info, +policy_rr_info. 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 @@ -

processor_assign

Function - Assign a processor to a processor set.

SYNOPSIS

kern_return_t	processor_assign
		(processor_t	processor,
		processor_set_t	new_set,
		boolean_t	wait);

PARAMETERS

processor
[in processor send right] The processor to be assigned.
new_set
[in processor-set-control send right] The control port for the processor set into which the processor is to be assigned.
wait
[in scalar] True if the call should wait for the completion of the assignment.

DESCRIPTION

The processor_assign function assigns processor to the set new_set. 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.

The wait 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 wait to FALSE allows assignment requests to be queued and performed more quickly, especially if the kernel has more than one dedicated internal thread for processor assignment.

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_set_create, processor_set_info, task_assign, thread_assign. \ No newline at end of file +

processor_assign

+
+

+Function - Assign a processor to a processor set. +

SYNOPSIS

+
+kern_return_t	processor_assign
+		(processor_t	processor,
+		processor_set_t	new_set,
+		boolean_t	wait);
+
+

PARAMETERS

+
+
processor +
+[in processor send right] +The processor to be assigned. +
new_set +
+[in processor-set-control send right] +The control port for the processor +set into which the processor is to be assigned. +
wait +
+[in scalar] +True if the call should wait for the completion of the +assignment. +
+

DESCRIPTION

+

+The processor_assign function assigns processor to +the set new_set. 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. +

+The wait 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 wait to FALSE allows +assignment requests to be queued and performed more quickly, especially +if the kernel has +more than one dedicated internal thread for processor assignment. +

+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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_set_create, +processor_set_info, +task_assign, +thread_assign. 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 @@ -

processor_basic_info

Structure - Defines the basic information about a processor.

SYNOPSIS

struct processor_basic_info
{
       cpu_type_t        cpu_type;
       cpu_subtype_t  cpu_subtype;
       boolean_t          running;
       int               slot_num;
       boolean_t        is_master;
};

typedef struct processor_basic_info* processor_basic_info_t;

FIELDS

cpu_type
Type of CPU

cpu_subtype
Sub-type of CPU

running
True if the CPU is running

slot_num
Slot number of the CPU

is_master
True if this is the master processor

DESCRIPTION

The processor_basic_info structure defines the information available about a processor slot.

RELATED INFORMATION

Functions: processor_info. \ No newline at end of file +

processor_basic_info

+
+

+Structure - Defines the basic information about a processor. +

SYNOPSIS

+
+struct processor_basic_info
+{
+       cpu_type_t        cpu_type;
+       cpu_subtype_t  cpu_subtype;
+       boolean_t          running;
+       int               slot_num;
+       boolean_t        is_master;
+};
+
+typedef struct processor_basic_info* processor_basic_info_t;
+
+

FIELDS

+
+
cpu_type +
+Type of CPU +

+

cpu_subtype +
+Sub-type of CPU +

+

running +
+True if the CPU is running +

+

slot_num +
+Slot number of the CPU +

+

is_master +
+True if this is the master processor +
+

DESCRIPTION

+

+The processor_basic_info structure defines the information +available about a processor slot. +

RELATED INFORMATION

+

+Functions: +processor_info. 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 @@ -

processor_control

Function - Perform caller-specified operation on target processor. (Protected Interface.)

SYNOPSIS

kern_return_t	processor_control
		(processor_t	processor,
		processor_info_t	cmd,
		mach_msg_type_number_t*	count);

PARAMETERS

processor
[in processor send right] The processor to be controlled.
cmd
[pointer to in array of natural-sized units] An array containing the command to be applied to the processor.
count
[in scalar] The size of the cmd array (in natural-sized units).

DESCRIPTION

The processor_control function allows privileged software to control a processor in a multi-processor that so allows it. The interpretation of cmd is machine dependent.

NOTES

These operations are machine dependent. They may do nothing.

RETURN VALUES

KERN_FAILURE
The operation was not performed. A likely reason is that it is not supported on this processor.

RELATED INFORMATION

Functions: processor_start, processor_exit, processor_info, host_processors. \ No newline at end of file +

processor_control

+
+

+Function - Perform caller-specified operation on target processor. (Protected Interface.) +

SYNOPSIS

+
+kern_return_t	processor_control
+		(processor_t	processor,
+		processor_info_t	cmd,
+		mach_msg_type_number_t*	count);
+
+

PARAMETERS

+
+
processor +
+[in processor send right] +The processor to be controlled. +
cmd +
+[pointer to in array of natural-sized units] +An array containing the +command to be applied to the processor. +
count +
+[in scalar] +The size of the cmd array (in natural-sized units). +
+

DESCRIPTION

+

+The processor_control function allows privileged software +to control a +processor in a multi-processor that so allows it. The interpretation +of cmd is machine +dependent. +

NOTES

+

+These operations are machine dependent. They may do nothing. +

RETURN VALUES

+
+
KERN_FAILURE +
+The operation was not performed. A likely reason is that it +is not supported on this processor. +
+

RELATED INFORMATION

+

+Functions: +processor_start, +processor_exit, +processor_info, +host_processors. 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 @@ -

processor_exit

Function - Exit a processor.

SYNOPSIS

kern_return_t	processor_exit
		(processor_t	processor);

PARAMETERS

processor
[in processor send right] The processor to be controlled.

DESCRIPTION

The processor_exit 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.

NOTES

This operation is machine dependent. It may do nothing.

CAUTIONS

The ability to restart an exited processor is machine dependent.

RETURN VALUES

KERN_FAILURE
The operation was not performed. A likely reason is that it is not supported on this processor.

RELATED INFORMATION

Functions: processor_control, processor_start, processor_info, host_processors. \ No newline at end of file +

processor_exit

+
+

+Function - Exit a processor. +

SYNOPSIS

+
+kern_return_t	processor_exit
+		(processor_t	processor);
+
+

PARAMETERS

+
+
processor +
+[in processor send right] +The processor to be controlled. +
+

DESCRIPTION

+

+The processor_exit 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. +

NOTES

+

+This operation is machine dependent. It may do nothing. +

CAUTIONS

+

+The ability to restart an exited processor is machine dependent. +

RETURN VALUES

+
+
KERN_FAILURE +
+The operation was not performed. A likely reason is that it +is not supported on this processor. +
+

RELATED INFORMATION

+

+Functions: +processor_control, +processor_start, +processor_info, +host_processors. 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 @@ -

processor_get_assignment

Function - Get current assignment for a processor.

SYNOPSIS

kern_return_t	processor_get_assignment
		(processor_t	processor,
		processor_set_name_t	assigned_set);

PARAMETERS

processor
[in processor send right] The processor whose assignment is desired.
new_set
[out processor-set-name send right] The name port for the processor set to which processor is currently assigned.

DESCRIPTION

The processor_get_assignment function returns the name port for the processor set to which a desired processor is currently assigned.

RETURN VALUES

KERN_FAILURE
Processor is either shut down of off-line.

RELATED INFORMATION

Functions: processor_assign, processor_set_create, processor_info, task_assign, thread_assign. \ No newline at end of file +

processor_get_assignment

+
+

+Function - Get current assignment for a processor. +

SYNOPSIS

+
+kern_return_t	processor_get_assignment
+		(processor_t	processor,
+		processor_set_name_t	assigned_set);
+
+

PARAMETERS

+
+
processor +
+[in processor send right] +The processor whose assignment is desired. +
new_set +
+[out processor-set-name send right] +The name port for the processor +set to which processor is currently assigned. +
+

DESCRIPTION

+

+The processor_get_assignment function returns the name port for the +processor set to which a desired processor is currently assigned. +

RETURN VALUES

+
+
KERN_FAILURE +
+Processor is either shut down of off-line. +
+

RELATED INFORMATION

+

+Functions: +processor_assign, +processor_set_create, +processor_info, +task_assign, +thread_assign. 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 @@ -

processor_info

Function - Return information about a processor.

SYNOPSIS

kern_return_t	processor_info
		(processor_t	processor,
		processor_flavor_t	flavor,
		host_t	host,
		processor_info_t	processor_info,
		mach_msg_type_number_t	processor_info_count);

PARAMETERS

processor
[in processor send right] A processor port for which information is desired.
flavor
[in scalar] The type of information requested.
PROCESSOR_BASIC_INFO
Basic information, slot number, running status, etc. The returned structure is processor_basic_info.
host
[out host-name send right] The host on which the processor resides. This is the host name port.
processor_info
[out structure] Information about the processor.
processor_info_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The processor_info function returns selected information for a processor, as specified by flavor.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_start, processor_exit, processor_control, host_processors.

Data Structures: processor_basic_info. \ No newline at end of file +

processor_info

+
+

+Function - Return information about a processor. +

SYNOPSIS

+
+kern_return_t	processor_info
+		(processor_t	processor,
+		processor_flavor_t	flavor,
+		host_t	host,
+		processor_info_t	processor_info,
+		mach_msg_type_number_t	processor_info_count);
+
+

PARAMETERS

+
+
processor +
+[in processor send right] +A processor port for which information is +desired. +
flavor +
+[in scalar] +The type of information requested. +
+
PROCESSOR_BASIC_INFO +
+Basic information, slot number, running status, etc. The +returned structure is processor_basic_info. +
+
host +
+[out host-name send right] +The host on which the processor resides. +This is the host name port. +
processor_info +
+[out structure] +Information about the processor. +
processor_info_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The processor_info function returns selected information +for a processor, as specified by flavor. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_start, +processor_exit, +processor_control, +host_processors. +

+Data Structures: +processor_basic_info. 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 @@ -

processor_set_basic_info

Structure - Defines the basic information about a processor set.

SYNOPSIS

struct processor_set_basic_info
{
       int        processor_count;
       int         default_policy;
};

typedef struct processor_set_basic_info* processor_set_basic_info_t;

FIELDS

processor_count
Number of processors in this set.

default_policy
Default policy to assign to threads whose otherwise assigned policy is not enabled.

DESCRIPTION

The processor_set_basic_info structure defines the basic information available about a processor set.

RELATED INFORMATION

Functions: processor_set_info.

Data Structures: processor_set_load_info. \ No newline at end of file +

processor_set_basic_info

+
+

+Structure - Defines the basic information about a processor set. +

SYNOPSIS

+
+struct processor_set_basic_info
+{
+       int        processor_count;
+       int         default_policy;
+};
+
+typedef struct processor_set_basic_info* processor_set_basic_info_t;
+
+

FIELDS

+
+
processor_count +
+Number of processors in this set. +

+

default_policy +
+Default policy to assign to threads whose otherwise assigned policy is +not enabled. +
+

DESCRIPTION

+

+The processor_set_basic_info structure defines the +basic information available about a processor set. +

RELATED INFORMATION

+

+Functions: +processor_set_info. +

+Data Structures: +processor_set_load_info. 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 @@ -

processor_set_create

Function - Create a new processor set object.

SYNOPSIS

kern_return_t	processor_set_create
		(host_t	host_name,
		processor_set_t	new_set,
		processor_set_name_t	new_name);

PARAMETERS

host_name
[in host-name send right] The name (or control) port for the host on which the set is to be created.
new_set
[out processor-set-control send right] Control port used for performing operations on the new set.
new_name
[out processor-set-name send right] Name port used to identify the new set and obtain information about it.

DESCRIPTION

The processor_set_create function creates a new processor set and returns the two ports associated with it. The port returned in new_set is the control port representing the set. It is used to perform operations such as assigning processors, tasks or threads. The port returned in new_name is the name port which identifies the set, and is used to obtain information about the set.

RETURN VALUES

Only generic values apply.

RELATED INFORMATION

Functions: processor_set_destroy, processor_set_info, processor_assign, task_assign, thread_assign. \ No newline at end of file +

processor_set_create

+
+

+Function - Create a new processor set object. +

SYNOPSIS

+
+kern_return_t	processor_set_create
+		(host_t	host_name,
+		processor_set_t	new_set,
+		processor_set_name_t	new_name);
+
+

PARAMETERS

+
+
host_name +
+[in host-name send right] +The name (or control) port for the host on +which the set is to be created. +
new_set +
+[out processor-set-control send right] +Control port used for performing +operations on the new set. +
new_name +
+[out processor-set-name send right] +Name port used to identify the new +set and obtain information about it. +
+

DESCRIPTION

+

+The processor_set_create function creates a new processor +set and returns the +two ports associated with it. The port returned in new_set is the control port +representing the set. It is used to perform operations such +as assigning processors, +tasks or threads. The port returned in new_name is the name port which +identifies the set, and is used to obtain information about the set. +

RETURN VALUES

+

+Only generic values apply. +

RELATED INFORMATION

+

+Functions: +processor_set_destroy, +processor_set_info, +processor_assign, +task_assign, +thread_assign. 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 @@ -

processor_set_default

Function - Return the default processor set.

SYNOPSIS

kern_return_t	processor_set_default
		(host_t	host,
		processor_set_name_t	default_set_name);

PARAMETERS

host
[in host-name send right] The name (or control) port for the host for which the default processor set is desired.
default_set_name
[out processor-set-name send right] The returned name port for the default processor set.

DESCRIPTION

The processor_set_default 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_set_info, thread_assign, task_assign. \ No newline at end of file +

processor_set_default

+
+

+Function - Return the default processor set. +

SYNOPSIS

+
+kern_return_t	processor_set_default
+		(host_t	host,
+		processor_set_name_t	default_set_name);
+
+

PARAMETERS

+
+
host +
+[in host-name send right] +The name (or control) port for the host for +which the default processor set is desired. +
default_set_name +
+[out processor-set-name send right] +The returned name port for the +default processor set. +
+

DESCRIPTION

+

+The processor_set_default 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_set_info, +thread_assign, +task_assign. 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 @@ -

processor_set_destroy

Function - Destroy the target processor set object.

SYNOPSIS

kern_return_t	processor_set_destroy
		(processor_set_t	processor_set);

PARAMETERS

processor_set
[in processor-set-control send right] The control port for the processor set to be destroyed.

DESCRIPTION

The processor_set_destroy 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.

RETURN VALUES

KERN_DEFAULT_SET
An attempt was made to destroy the default processor set.

RELATED INFORMATION

Functions: processor_set_create, processor_assign, task_assign, thread_assign. \ No newline at end of file +

processor_set_destroy

+
+

+Function - Destroy the target processor set object. +

SYNOPSIS

+
+kern_return_t	processor_set_destroy
+		(processor_set_t	processor_set);
+
+

PARAMETERS

+
+
processor_set +
+[in processor-set-control send right] +The control port for the processor +set to be destroyed. +
+

DESCRIPTION

+

+The processor_set_destroy 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. +

RETURN VALUES

+
+
KERN_DEFAULT_SET +
+An attempt was made to destroy the default processor set. +
+

RELATED INFORMATION

+

+Functions: +processor_set_create, +processor_assign, +task_assign, +thread_assign. 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 @@ -

processor_set_info

Function - Return processor set state according to caller-specified flavor.

SYNOPSIS

kern_return_t	processor_set_info
		(processor_set_name_t	processor_set_name,
		int	flavor,
		host_t	host,
		processor_set_info_t	processor_set_info,
		mach_msg_type_number_t	processor_set_info_count);

PARAMETERS

processor_set_name
[in processor-set-name send right] A processor set name (or control) port for which information is desired.
flavor
[in scalar] The type of information requested.
PROCESSOR_SET_BASIC_INFO
Basic information concerning the processor set (number of assigned processors and default policy). The returned structure is defined by processor_set_basic_info.
PROCESSOR_SET_TIMESHARE_DEFAULT
The base attributes for the timeshare scheduling policy. The returned structure is policy_timeshare_base.
PROCESSOR_SET_FIFO_DEFAULT
The base attributes for the FIFO scheduling policy. The returned structure is policy_fifo_base.
PROCESSOR_SET_RR_DEFAULT
The base attributes for the round-robin scheduling policy. The returned structure is policy_rr_base.
PROCESSOR_SET_TIMESHARE_LIMITS
Limits on the allowed timeshare policy attributes. The returned structure is defined by policy_timeshare_limit.
PROCESSOR_SET_RR_LIMITS
Limits on the allowed round robin policy attributes. The returned structure is defined by policy_rr_limit.
PROCESSOR_SET_FIFO_LIMITS
Limits on the allowed first-in, first-out policy attributes. The returned structure is defined by policy_fifo_limit.
PROCESSOR_SET_ENABLED_POLICIES
The set of enabled policies. The returned data is a bit-vector.
host
[out host-name send right] The name port for the host on which the processor set resides.
processor_set_info
[out structure] Information about the processor set.
processor_set_info_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The processor_set_info function returns selected information for a processor set, as specified by flavor.

NOTES

A processor set has a single default scheduling policy in effect for it (as returned by PROCESSOR_SET_BASIC_INFO), 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_set_statistics, processor_set_create, processor_set_default, processor_assign, processor_set_policy_control.

Data Structures: processor_set_basic_info, policy_timeshare_info, policy_rr_info, policy_fifo_info. \ No newline at end of file +

processor_set_info

+
+

+Function - Return processor set state according to caller-specified flavor. +

SYNOPSIS

+
+kern_return_t	processor_set_info
+		(processor_set_name_t	processor_set_name,
+		int	flavor,
+		host_t	host,
+		processor_set_info_t	processor_set_info,
+		mach_msg_type_number_t	processor_set_info_count);
+
+

PARAMETERS

+
+
processor_set_name +
+[in processor-set-name send right] +A processor set name (or control) +port for which information is desired. +
flavor +
+[in scalar] +The type of information requested. +
+
PROCESSOR_SET_BASIC_INFO +
+Basic information concerning the processor set (number of +assigned processors and default policy). The returned structure +is defined by processor_set_basic_info. +
PROCESSOR_SET_TIMESHARE_DEFAULT +
+The base attributes for the timeshare scheduling policy. The +returned structure is policy_timeshare_base. +
PROCESSOR_SET_FIFO_DEFAULT +
+The base attributes for the FIFO scheduling policy. The +returned structure is policy_fifo_base. +
PROCESSOR_SET_RR_DEFAULT +
+The base attributes for the round-robin scheduling policy. The +returned structure is policy_rr_base. +
PROCESSOR_SET_TIMESHARE_LIMITS +
+Limits on the allowed timeshare policy attributes. The +returned structure is defined by policy_timeshare_limit. +
PROCESSOR_SET_RR_LIMITS +
+Limits on the allowed round robin policy attributes. The +returned structure is defined by policy_rr_limit. +
PROCESSOR_SET_FIFO_LIMITS +
+Limits on the allowed first-in, first-out policy attributes. The +returned structure is defined by policy_fifo_limit. +
PROCESSOR_SET_ENABLED_POLICIES +
+The set of enabled policies. The returned data is a bit-vector. +
+
host +
+[out host-name send right] +The name port for the host on which the +processor set resides. +
processor_set_info +
+[out structure] +Information about the processor set. +
processor_set_info_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The processor_set_info function returns selected information +for a processor set, as specified by flavor. +

NOTES

+

+A processor set has a single default scheduling policy in effect for it (as +returned by PROCESSOR_SET_BASIC_INFO), 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_set_statistics, +processor_set_create, +processor_set_default, +processor_assign, +processor_set_policy_control. +

+Data Structures: +processor_set_basic_info, +policy_timeshare_info, +policy_rr_info, +policy_fifo_info. 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 @@ -

processor_set_load_info

Structure - Defines the scheduling statistics for a processor set.

SYNOPSIS

struct processor_set_load_info
{
       int            task_count;
       int          thread_count;
       integer_t    load_average;
       integer_t     mach_factor;
};

typedef struct processor_set_load_info* processor_set_load_info_t;

FIELDS

task_count
Number of tasks currently assigned to this processor set

thread_count
Number of threads currently assigned to this processor set

load_average
Average number of runnable processes divided by number of CPUs

mach_factor
The processing resources available to a new thread\(emthe number of CPUs divided by (1 + the number of threads)

DESCRIPTION

The processor_set_load_info structure defines the scheduling statistics maintained for a processor set.

RELATED INFORMATION

Data Structures: processor_set_basic_info. \ No newline at end of file +

processor_set_load_info

+
+

+Structure - Defines the scheduling statistics for a processor set. +

SYNOPSIS

+
+struct processor_set_load_info
+{
+       int            task_count;
+       int          thread_count;
+       integer_t    load_average;
+       integer_t     mach_factor;
+};
+
+typedef struct processor_set_load_info* processor_set_load_info_t;
+
+

FIELDS

+
+
task_count +
+Number of tasks currently assigned to this processor set +

+

thread_count +
+Number of threads currently assigned to this processor set +

+

load_average +
+Average number of runnable processes divided by number of CPUs +

+

mach_factor +
+The processing resources available to a new thread\(emthe number of +CPUs divided by (1 + the number of threads) +
+

DESCRIPTION

+

+The processor_set_load_info structure defines the scheduling +statistics +maintained for a processor set. +

RELATED INFORMATION

+

+

+Data Structures: +processor_set_basic_info. 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 @@ -

processor_set_max_priority

Function - Sets the maximum scheduling priority for a processor set.

SYNOPSIS

#include< mach/mach_host.h>

kern_return_t	processor_set_max_priority
		(processor_set_t	processor_set,
		int	priority,
		boolean_t	change_threads);

PARAMETERS

processor_set
[in processor-set-control port] The control port for the processor set whose maximum scheduling priority is to be set.
priority
[in scalar] The new priority for the processor set.
change_threads
[in scalar] True if the maximum priority of existing threads assigned to this processor set should also be changed.

DESCRIPTION

The processor_set_max_priority function sets the maximum scheduling priority for processor_set. The maximum priority of a processor set is used only when creating new threads. A new thread's maximum priority is set to that of its assigned processor set. When assigned to a processor set, a thread's maximum priority is reduced, if necessary, to that of its new processor set; its current priority is also reduced, as needed. Changing the maximum priority of a processor set does not affect the priority of the currently assigned threads unless change_threads is TRUE. If this priority change violates the maximum priority of some threads, their maximum priorities will be reduced to match.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: thread_assign. \ No newline at end of file +

processor_set_max_priority

+
+

+Function - Sets the maximum scheduling priority for a processor set. +

SYNOPSIS

+
+#include< mach/mach_host.h>
+
+kern_return_t	processor_set_max_priority
+		(processor_set_t	processor_set,
+		int	priority,
+		boolean_t	change_threads);
+
+

PARAMETERS

+
+
processor_set +
+[in processor-set-control port] The control port for the processor set whose maximum scheduling priority is to be set. +
priority +
+[in scalar] The new priority for the processor set. +
change_threads +
+[in scalar] True if the maximum priority of existing threads assigned to this processor set should also be changed. +
+

DESCRIPTION

+

+The processor_set_max_priority +function sets the maximum scheduling priority for +processor_set. The maximum priority of a +processor set is used only when creating new threads. A new thread's +maximum priority is set to that of its assigned processor +set. When assigned to a processor set, a thread's maximum +priority is reduced, if necessary, to that of its new +processor set; its current priority is also reduced, as +needed. Changing the maximum priority of a processor set +does not affect the priority of the currently assigned +threads unless change_threads is TRUE. If this +priority change violates the maximum priority of +some threads, their maximum priorities will be reduced to match. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +thread_assign. 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 @@ -

processor_set_statistics

Function - Return scheduling statistics for a processor set.

SYNOPSIS

kern_return_t	processor_set_statistics
		(processor_set_t	processor_set_control,
		processor_set_flavor_t	flavor,
		processor_set_info_t	processor_set_info,
		mach_msg_type_number_t	processor_set_info_count);

PARAMETERS

processor_set_control
[in processor-set-control send right] A processor set control port for which information is desired.
flavor
[in scalar] The type of information requested.
PROCESSOR_SET_LOAD_INFO
Load statistics for the processor set. The returned structure is processor_set_load_info.
processor_set_info
[out structure] Information about the processor set.
processor_set_info_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The processor_set_statistics function returns statistics for a processor set as specified by flavor.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_set_info.

Data Structures: processor_set_load_info. \ No newline at end of file +

processor_set_statistics

+
+

+Function - Return scheduling statistics for a processor set. +

SYNOPSIS

+
+kern_return_t	processor_set_statistics
+		(processor_set_t	processor_set_control,
+		processor_set_flavor_t	flavor,
+		processor_set_info_t	processor_set_info,
+		mach_msg_type_number_t	processor_set_info_count);
+
+

PARAMETERS

+
+
processor_set_control +
+[in processor-set-control send right] +A processor set control port for +which information is desired. +
flavor +
+[in scalar] +The type of information requested. +
+
PROCESSOR_SET_LOAD_INFO +
+Load statistics for the processor set. The returned structure is +processor_set_load_info. +
+
processor_set_info +
+[out structure] +Information about the processor set. +
processor_set_info_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The processor_set_statistics function returns statistics +for a processor set as specified by flavor. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_set_info. +

+Data Structures: +processor_set_load_info. 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 @@ -

processor_set_tasks

Function - Return a list of pointers to all tasks currently assigned to the target processor set.

SYNOPSIS

kern_return_t	processor_set_tasks
		(processor_set_t	processor_set,
		task_port_array_t	task_list,
		mach_msg_type_number_t*	task_count);

PARAMETERS

processor_set
[in processor-set-control send right] A processor set control port for which information is desired.
task_list
[out pointer to dynamic array of task send rights] The returned set of ports naming the tasks currently assigned to processor_set.
task_count
[out scalar] The number of tasks returned in task_list.

DESCRIPTION

The processor_set_tasks function returns send rights to the kernel ports for each task currently assigned to processor_set.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_set_threads, task_assign, thread_assign. \ No newline at end of file +

processor_set_tasks

+
+

+Function - Return a list of pointers to all tasks currently assigned to the target processor set. +

SYNOPSIS

+
+kern_return_t	processor_set_tasks
+		(processor_set_t	processor_set,
+		task_port_array_t	task_list,
+		mach_msg_type_number_t*	task_count);
+
+

PARAMETERS

+
+
processor_set +
+[in processor-set-control send right] +A processor set control port for +which information is desired. +
task_list +
+[out pointer to dynamic array of task send rights] +The returned set of +ports naming the tasks currently assigned to processor_set. +
task_count +
+[out scalar] +The number of tasks returned in task_list. +
+

DESCRIPTION

+

+The processor_set_tasks function returns send rights +to the kernel ports for each task currently assigned to processor_set. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_set_threads, +task_assign, +thread_assign. 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 @@ -

processor_set_threads

Function - Return a list of pointers to all threads currently assigned to the target processor set.

SYNOPSIS

kern_return_t	processor_set_threads
		(processor_set_t	processor_set,
		thread_port_array_t	thread_list,
		mach_msg_type_number_t*	thread_count);

PARAMETERS

processor_set
[in processor-set-control send right] A processor set control port for which information is desired.
thread_list
[out pointer to dynamic array of thread send rights] The returned set of ports naming the threads currently assigned to processor_set.
thread_count
[out scalar] The number of threads returned in thread_list.

DESCRIPTION

The processor_set_threads function returns send rights to the kernel ports for each thread currently assigned to processor_set.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: processor_set_tasks, task_assign, thread_assign. \ No newline at end of file +

processor_set_threads

+
+

+Function - Return a list of pointers to all threads currently assigned to the target processor set. +

SYNOPSIS

+
+kern_return_t	processor_set_threads
+		(processor_set_t	processor_set,
+		thread_port_array_t	thread_list,
+		mach_msg_type_number_t*	thread_count);
+
+

PARAMETERS

+
+
processor_set +
+[in processor-set-control send right] +A processor set control port for +which information is desired. +
thread_list +
+[out pointer to dynamic array of thread send rights] +The returned set of +ports naming the threads currently assigned to processor_set. +
thread_count +
+[out scalar] +The number of threads returned in thread_list. +
+

DESCRIPTION

+

+The processor_set_threads function returns send rights +to the kernel ports for each thread currently assigned to processor_set. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +processor_set_tasks, +task_assign, +thread_assign. 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 @@ -

processor_start

Function - Start a processor.

SYNOPSIS

#include<mach/mach_host.h>

kern_return_t	processor_start
		(processor_t	processor);

PARAMETERS

processor
[in processor send right] The processor to be controlled.

DESCRIPTION

The processor_start 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.

NOTES

This operation is machine dependent. It may do nothing.

CAUTIONS

The ability to restart an exited processor is machine dependent.

RETURN VALUES

KERN_FAILURE
The operation was not performed. A likely reason is that it is not supported on this processor.

RELATED INFORMATION

Functions: processor_control, processor_exit, processor_info, host_processors. \ No newline at end of file +

processor_start

+
+

+Function - Start a processor. +

SYNOPSIS

+
+#include<mach/mach_host.h>
+
+kern_return_t	processor_start
+		(processor_t	processor);
+
+

PARAMETERS

+
+
processor +
+[in processor send right] +The processor to be controlled. +
+

DESCRIPTION

+

+The processor_start 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. +

NOTES

+

+This operation is machine dependent. It may do nothing. +

CAUTIONS

+

+The ability to restart an exited processor is machine dependent. +

RETURN VALUES

+
+
KERN_FAILURE +
+The operation was not performed. A likely reason is that it +is not supported on this processor. +
+

RELATED INFORMATION

+

+Functions: +processor_control, +processor_exit, +processor_info, +host_processors. 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 @@ -

prof_server

Function - Handle the next kernel-generated PC sample message.

SYNOPSIS

boolean_t	prof_server
		(mach_msg_header_t	request_msg,
		mach_msg_header_t	reply_ms);

PARAMETERS

in_msg
[pointer to in structure] The sample message received from the kernel.

out_msg
[out structure] Not used.

DESCRIPTION

The prof_server 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 task_sample or thread_sample. The prof_server function performs all necessary argument handling for this kernel message and calls the appropriate handling function. These functions must be supplied by the caller.

RETURN VALUES

TRUE
The message was handled and the appropriate function was called.

FALSE
The message did not apply to the sample mechanism and no other action was taken.

RELATED INFORMATION

Functions: receive_samples. \ No newline at end of file +

prof_server

+
+

+Function - Handle the next kernel-generated PC sample message. +

SYNOPSIS

+
+boolean_t	prof_server
+		(mach_msg_header_t	request_msg,
+		mach_msg_header_t	reply_ms);
+
+

PARAMETERS

+
+

+

in_msg +
+[pointer to in structure] +The sample message received from the kernel. +

+

out_msg +
+[out structure] +Not used. +
+

DESCRIPTION

+

+The prof_server 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 +task_sample or thread_sample. The prof_server +function performs all +necessary argument handling for this kernel message and calls the appropriate +handling function. These functions must be supplied by the caller. +

RETURN VALUES

+
+

+

TRUE +
+The message was handled and the appropriate function was called. +

+

FALSE +
+The message did not apply to the sample mechanism and no other +action was taken. +
+

RELATED INFORMATION

+

+Functions: +receive_samples. 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 @@ -

receive_samples

Server Interface - Handles the occurrence of a PC sampling message

SYNOPSIS

kern_return_t   receive_samples
                (mach_port_t                     sample_port,
                 sample_array_t                      samples,
                 mach_msg_type_number_t         sample_count);

PARAMETERS

sample_port
[in sample (receive) right] The port to which the sample message was sent.
samples
[pointer to in array of vm_address_t] An array of PC sample values.
sample_count
[in scalar] The number of values in samples.

DESCRIPTION

A receive_samples function is called by prof_server as the result of a kernel message indicating that a set of program counter samples has been gathered. The parameter sample_port specifies the port named via a previous call to task_sample or thread_sample.

NOTES

This interface is machine word length specific because of the virtual addresses in the samples parameter.

RETURN VALUE

Irrelevant.

RELATED INFORMATION

Functions: task_sample, thread_sample, prof_server. \ No newline at end of file +

receive_samples

+

+Server Interface - Handles the occurrence of a PC sampling message + +

SYNOPSIS

+
+kern_return_t   receive_samples
+                (mach_port_t                     sample_port,
+                 sample_array_t                      samples,
+                 mach_msg_type_number_t         sample_count);
+
+

PARAMETERS

+
+
sample_port +
+[in sample (receive) right] The port to which the sample message was +sent. + +
samples +
+[pointer to in array of vm_address_t] An array of PC sample values. + +
sample_count +
+[in scalar] The number of values in samples. +
+ +

DESCRIPTION

+

+A receive_samples function is called by +prof_server as the result of a kernel +message indicating that a set of program counter samples has been gathered. +The parameter sample_port specifies the port named via +a previous call to task_sample +or thread_sample. + +

NOTES

+

+This interface is machine word length specific because of the virtual addresses +in the samples parameter. + +

RETURN VALUE

+

+Irrelevant. + +

RELATED INFORMATION

+

+Functions: +task_sample, +thread_sample, +prof_server. 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 @@ -

semaphore_create

Function - Create a new semaphore.

SYNOPSIS

kern_return_t	semaphore_create
		(task_t                   task,
		 semaphore_t        *semaphore,
		 int                    policy,
		 int                     value);

PARAMETERS

task
[in task port] The task receiving the send right of the newly created semaphore.

semaphore
[out send right] The port naming the created semaphore.

policy
[in scalar] The blocked thread wakeup policy for the newly created semaphore. Valid policies are:

SYNC_POLICY_FIFO
a first-in-first-out policy for scheduling thread wakeup.

SYNC_POLICY_FIXED_PRIORITY
a fixed priority policy for scheduling thread wakeup.

value
[in scalar] The initial value of the semaphore count.

DESCRIPTION

The semaphore_create 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 semaphore_create) and exporting (via device_get_status) semaphores for user level access. Device driver semaphore creation is done at device initialization time. Device drivers may support multiple semaphores.

RETURN VALUES

KERN_INVALID_ARGUMENT
The task argument or the policy argument was invalid, or the initial value of the semaphore was invalid.

KERN_RESOURCE_SHORTAGE
The kernel could not allocate the semaphore.

KERN_SUCCESS
The semaphore was successfully created.

RELATED INFORMATION

Functions: semaphore_destroy, semaphore_signal, semaphore_signal_all, semaphore_wait, device_get_status. \ No newline at end of file +

semaphore_create

+
+

+Function - Create a new semaphore. +

SYNOPSIS

+
+kern_return_t	semaphore_create
+		(task_t                   task,
+		 semaphore_t        *semaphore,
+		 int                    policy,
+		 int                     value);
+
+

PARAMETERS

+
+
task +
+[in task port] The task receiving the send right of the newly created semaphore. +

+

semaphore +
+[out send right] The port naming the created semaphore. +

+

policy +
+[in scalar] The blocked thread wakeup policy for the newly created semaphore. Valid policies are: +
+

+

SYNC_POLICY_FIFO +
+a first-in-first-out policy for scheduling thread wakeup. +

+

SYNC_POLICY_FIXED_PRIORITY +
+a fixed priority policy for scheduling thread wakeup. +
+

+

value +
+[in scalar] The initial value of the semaphore count. +
+

DESCRIPTION

+

+The semaphore_create 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 +semaphore_create) and exporting (via device_get_status) +semaphores for +user level access. Device driver semaphore creation is done at device +initialization time. Device drivers may support multiple semaphores. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+The task argument or the policy argument was invalid, + or the initial value of the semaphore was invalid. +

+

KERN_RESOURCE_SHORTAGE +
+The kernel could not allocate the semaphore. +

+

KERN_SUCCESS +
+The semaphore was successfully created. +
+

RELATED INFORMATION

+

+Functions: +semaphore_destroy, +semaphore_signal, +semaphore_signal_all, +semaphore_wait, +device_get_status. 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 @@ -

semaphore_destroy

Function - Destroy a semaphore.

SYNOPSIS

kern_return_t   semaphore_destroy
                (task_t                                    task,
                 semaphore_t                          semaphore);

PARAMETERS

task
[in task port] The task associated with the target semaphore.

semaphore
[in send right] The port naming the semaphore to be destroyed.

DESCRIPTION

The semaphore_destroy 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 semaphore_wait call indicating that the semaphore was destroyed. A call to semaphore_destroy succeeds only if the semaphore is associated with the specified task.

RETURN VALUES

KERN_INVALID_ARGUMENT
Either, or both, the task or semaphore arguments were invalid.

KERN_INVALID_RIGHT
The specified task does not own the specified semaphore.

KERN_TERMINATED
The specified semaphore was previously destroyed.

KERN_SUCCESS
The semaphore was destroyed.

RELATED INFORMATION

Functions: semaphore_create, semaphore_signal, semaphore_signal_all, semaphore_wait, device_get_status. \ No newline at end of file +

semaphore_destroy

+
+

+Function - Destroy a semaphore. +

SYNOPSIS

+
+kern_return_t   semaphore_destroy
+                (task_t                                    task,
+                 semaphore_t                          semaphore);
+
+

PARAMETERS

+
+

+

task +
+[in task port] The task associated with the target semaphore. +

+

semaphore +
+[in send right] The port naming the semaphore to be destroyed. +
+

DESCRIPTION

+

+The semaphore_destroy 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 +semaphore_wait +call indicating that the semaphore was destroyed. A call to +semaphore_destroy succeeds only if the semaphore is associated +with the specified task. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+Either, or both, the task or semaphore arguments were invalid. +

+

KERN_INVALID_RIGHT +
+The specified task does not own the specified semaphore. +

+

KERN_TERMINATED +
+The specified semaphore was previously destroyed. +

+

KERN_SUCCESS +
+The semaphore was destroyed. +
+

RELATED INFORMATION

+

+Functions: +semaphore_create, +semaphore_signal, +semaphore_signal_all, +semaphore_wait, +device_get_status. 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 @@ -

semaphore_signal

Function - Increments the semaphore count.

SYNOPSIS

kern_return_t   semaphore_signal
                (semaphore_t                          semaphore);

PARAMETERS

semaphore
[in send right] The port naming the semaphore to be signalled.

DESCRIPTION

The semaphore_signal 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 semaphore_create). Device driver interrupt service routines may safely execute semaphore_signal operations without causing a deadlock.

RETURN VALUES

KERN_INVALID_ARGUMENT
The specified semaphore is invalid.

KERN_TERMINATED
The specified semaphore has been destroyed.

KERN_SUCCESS
The semaphore has been signalled.

RELATED INFORMATION

Functions: semaphore_create, semaphore_destroy, semaphore_signal_all, semaphore_wait, device_get_status. \ No newline at end of file +

semaphore_signal

+
+

+Function - Increments the semaphore count. +

SYNOPSIS

+
+kern_return_t   semaphore_signal
+                (semaphore_t                          semaphore);
+
+

PARAMETERS

+
+

+

semaphore +
+[in send right] The port naming the semaphore to be signalled. +
+

DESCRIPTION

+

+The semaphore_signal 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 semaphore_create). +Device driver interrupt service routines may safely execute +semaphore_signal operations without causing a deadlock. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+The specified semaphore is invalid. +

+

KERN_TERMINATED +
+The specified semaphore has been destroyed. +

+

KERN_SUCCESS +
+The semaphore has been signalled. +
+

RELATED INFORMATION

+

+Functions: +semaphore_create, +semaphore_destroy, +semaphore_signal_all, +semaphore_wait, +device_get_status. 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 @@ -

semaphore_signal_all

Function - Wake up all threads blocked on a semaphore.

SYNOPSIS

kern_return_t   semaphore_signal_all
                (semaphore_t                          semaphore);

PARAMETERS

semaphore
[in send right] The port naming the semaphore to be signalled.

DESCRIPTION

The semaphore_signal_all function wakes up all of the threads blocked on the semaphore. The semaphore count is reset to zero.

RETURN VALUES

KERN_INVALID_ARGUMENT
The specified semaphore is invalid.

KERN_TERMINATED
The specified semaphore has been destroyed.

KERN_SUCCESS
The semaphore has been signalled.

RELATED INFORMATION

Functions: semaphore_create, semaphore_destroy, semaphore_signal, \ No newline at end of file +

semaphore_signal_all

+
+

+Function - Wake up all threads blocked on a semaphore. +

SYNOPSIS

+
+kern_return_t   semaphore_signal_all
+                (semaphore_t                          semaphore);
+
+

PARAMETERS

+
+

+

semaphore +
+[in send right] The port naming the semaphore to be signalled. +
+

DESCRIPTION

+

+The semaphore_signal_all function wakes up all of the +threads blocked on the semaphore. The semaphore count is reset to +zero. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+The specified semaphore is invalid. +

+

KERN_TERMINATED +
+The specified semaphore has been destroyed. +

+

KERN_SUCCESS +
+The semaphore has been signalled. +
+

RELATED INFORMATION

+

+Functions: +semaphore_create, +semaphore_destroy, +semaphore_signal, 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 @@ -

semaphore_wait

Function - Wait on the specified semaphore.

SYNOPSIS

kern_return_t   semaphore_wait
                (semaphore_t                          semaphore);

PARAMETERS

semaphore
[in send right] The port naming the semaphore that the wait operation is being performed upon.

DESCRIPTION

The semaphore_wait 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 semaphore_wait, since waiting on a semaphore at the ISR level may, and often will, lead to a deadlock.

RETURN VALUES

KERN_INVALID_ARGUMENT
The specified semaphore is invalid.

KERN_TERMINATED
The specified semaphore has been destroyed.

KERN_ABORTED
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. thread_terminate).

KERN_SUCCESS
The semaphore wait operation was successful.

RELATED INFORMATION

Functions: semaphore_create, semaphore_destroy, semaphore_signal, semaphore_signal_all, device_get_status. \ No newline at end of file +

semaphore_wait

+
+

+Function - Wait on the specified semaphore. +

SYNOPSIS

+
+kern_return_t   semaphore_wait
+                (semaphore_t                          semaphore);
+
+

PARAMETERS

+
+

+

semaphore +
+[in send right] The port naming the semaphore that the wait operation is being performed upon. +
+

DESCRIPTION

+

+The semaphore_wait 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 semaphore_wait, since waiting on a semaphore at the ISR level +may, and often will, lead to a deadlock. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+The specified semaphore is invalid. +

+

KERN_TERMINATED +
+The specified semaphore has been destroyed. +

+

KERN_ABORTED +
+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. thread_terminate). +

+

KERN_SUCCESS +
+The semaphore wait operation was successful. +
+

RELATED INFORMATION

+

+Functions: +semaphore_create, +semaphore_destroy, +semaphore_signal, +semaphore_signal_all, +device_get_status. 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 @@ -

seqnos_notify_server

Function - Handle the next kernel-generated IPC notification.

SYNOPSIS

boolean_t	seqnos_notify_server
		(mach_msg_header_t	request_msg,
		mach_msg_header_t	reply_ms);

PARAMETERS

in_msg
[pointer to in structure] The notification message received from the kernel.

out_msg
[out structure] Not used.

DESCRIPTION

The seqnos_notify_server 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 mach_msg or mach_port_request_notification call. The seqnos_notify_server function performs all necessary argument handling for this kernel message and calls the appropriate handling function. These functions must be supplied by the caller.

NOTES

seqnos_notify_server differs from notify_server in that it supplies message sequence numbers to the server interfaces.

RETURN VALUES

TRUE
The message was handled and the appropriate function was called.

FALSE
The message did not apply to the notification mechanism and no other action was taken.

RELATED INFORMATION

Functions: notify_server, do_seqnos_mach_notify_dead_name, do_seqnos_mach_notify_no_senders, do_seqnos_mach_notify_port_deleted, do_seqnos_mach_notify_send_once. \ No newline at end of file +

seqnos_notify_server

+
+

+Function - Handle the next kernel-generated IPC notification. +

SYNOPSIS

+
+boolean_t	seqnos_notify_server
+		(mach_msg_header_t	request_msg,
+		mach_msg_header_t	reply_ms);
+
+

PARAMETERS

+
+

+

in_msg +
+[pointer to in structure] +The notification message received from the +kernel. +

+

out_msg +
+[out structure] +Not used. +
+

DESCRIPTION

+

+The seqnos_notify_server 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 +mach_msg or mach_port_request_notification call. +The seqnos_notify_server function +performs all necessary argument handling for this kernel message and calls the +appropriate handling function. These functions must be supplied by the caller. +

NOTES

+

+seqnos_notify_server differs from notify_server +in that it supplies message +sequence numbers to the server interfaces. +

RETURN VALUES

+
+

+

TRUE +
+The message was handled and the appropriate function was called. +

+

FALSE +
+The message did not apply to the notification mechanism and no other +action was taken. +
+

RELATED INFORMATION

+

+Functions: +notify_server, +do_seqnos_mach_notify_dead_name, +do_seqnos_mach_notify_no_senders, +do_seqnos_mach_notify_port_deleted, +do_seqnos_mach_notify_send_once. 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 @@ -

task_assign

Function - Assign a task to a processor set.

SYNOPSIS

kern_return_t   task_assign
                (task_t                                    task,
                 processor_set_t                  processor_set,
                 boolean_t                       assign_threads);

PARAMETERS

task
[in task send right] The port for the task to be assigned.
processor_set
[in processor-set-control send right] The control port for the processor set into which the task is to be assigned.
assign_threads
[in scalar] True if this assignment should apply as well to the threads within the task.

DESCRIPTION

The task_assign function assigns task to the set 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.

If assign_threads is TRUE, existing threads within the task will also be assigned to the processor set.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_assign_default, task_get_assignment, processor_set_create, processor_set_info, thread_assign. \ No newline at end of file +

task_assign

+
+

+Function - Assign a task to a processor set. +

SYNOPSIS

+
+kern_return_t   task_assign
+                (task_t                                    task,
+                 processor_set_t                  processor_set,
+                 boolean_t                       assign_threads);
+
+

PARAMETERS

+
+
task +
+[in task send right] +The port for the task to be assigned. +
processor_set +
+[in processor-set-control send right] +The control port for the processor +set into which the task is to be assigned. +
assign_threads +
+[in scalar] +True if this assignment should apply as well to the threads +within the task. +
+

DESCRIPTION

+

+The task_assign function assigns task to the set +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. +

+If assign_threads is TRUE, existing threads within the task +will also be assigned to the processor set. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_assign_default, +task_get_assignment, +processor_set_create, +processor_set_info, +thread_assign. 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 @@ -

task_assign_default

Function - Assign a task to the default processor set.

SYNOPSIS

kern_return_t   task_assign_default
                (task_t                                    task,
                 boolean_t                       assign_threads);

PARAMETERS

task
[in task send right] The port for the task to be assigned.
assign_threads
[in scalar] True if this assignment should apply as well to the threads within the task.

DESCRIPTION

The task_assign_default function assigns task 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.

If assign_threads is TRUE, existing threads within the task will also be assigned to the processor set.

NOTES

This variant of task_assign exists because the control port for the default processor set is privileged, and therefore not available to most tasks.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_assign, task_get_assignment, processor_set_create, processor_set_info, thread_assign. \ No newline at end of file +

task_assign_default

+
+

+Function - Assign a task to the default processor set. +

SYNOPSIS

+
+kern_return_t   task_assign_default
+                (task_t                                    task,
+                 boolean_t                       assign_threads);
+
+

PARAMETERS

+
+
task +
+[in task send right] +The port for the task to be assigned. +
assign_threads +
+[in scalar] +True if this assignment should apply as well to the threads +within the task. +
+

DESCRIPTION

+

+The task_assign_default function assigns task 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. +

+If assign_threads is TRUE, existing threads within the +task will also be assigned to the processor set. +

NOTES

+

+This variant of task_assign exists because the control +port for the default +processor set is privileged, and therefore not available to most tasks. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_assign, +task_get_assignment, +processor_set_create, +processor_set_info, +thread_assign. 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 @@ -

task_basic_info

Structure - Defines basic information for a task.

SYNOPSIS

struct task_basic_info
{
       integer_t      suspend_count;
       vm_size_t       virtual_size;
       vm_size_t      resident_size;
       time_value_t       user_time;
       time_value_t     system_time;
       policy_t              policy;
};

typedef struct task_basic_info* task_basic_info_t;

FIELDS

suspend_count
The current suspend count for the task.

virtual_size
The number of virtual pages for the task.

resident_size
The number of resident pages for the task

user_time
The total user run time for terminated threads within the task.

system_time
The total system run time for terminated threads within the task.

policy
Default scheduling policy to apply to new threads.

DESCRIPTION

The task_basic_info structure defines the basic information array for tasks. The task_info function returns this array for a specified task.

NOTES

This structure is machine word length sensitive due to the presence of the virtual address sizes.

RELATED INFORMATION

Functions: task_info.

Data Structures: task_thread_times_info, policy_fifo_info, policy_rr_info, policy_timeshare_info. \ No newline at end of file +

task_basic_info

+
+

+Structure - Defines basic information for a task. +

SYNOPSIS

+
+struct task_basic_info
+{
+       integer_t      suspend_count;
+       vm_size_t       virtual_size;
+       vm_size_t      resident_size;
+       time_value_t       user_time;
+       time_value_t     system_time;
+       policy_t              policy;
+};
+
+typedef struct task_basic_info* task_basic_info_t;
+
+

FIELDS

+
+
suspend_count +
+The current suspend count for the task. +

+

virtual_size +
+The number of virtual pages for the task. +

+

resident_size +
+The number of resident pages for the task +

+

user_time +
+The total user run time for terminated threads within the task. +

+

system_time +
+The total system run time for terminated threads within the task. +

+

policy +
+Default scheduling policy to apply to new threads. +
+

DESCRIPTION

+

+The task_basic_info structure defines the basic information array for +tasks. The task_info function returns this array for a specified task. +

NOTES

+

+This structure is machine word length sensitive due +to the presence of the +virtual address sizes. +

RELATED INFORMATION

+

+Functions: +task_info. +

+Data Structures: +task_thread_times_info, +policy_fifo_info, +policy_rr_info, +policy_timeshare_info. 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 @@ -

task_create

Function - Create a new task.

SYNOPSIS

kern_return_t   task_create
                (task_t                             parent_task,
                 ledger_port_array_t                    ledgers,
                 int                               ledger_count,
                 boolean_t                       inherit_memory,
                 task_t                              child_task);

PARAMETERS

parent_task
[in task send right] The port for the task from which to draw the child task's port rights and address space.

ledgers
[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.

ledger_count
[in scalar] The number of ledger ports in the ledgers array.

inherit_memory
[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.

child_task
[out task send right] The kernel-assigned port for the new task.

DESCRIPTION

The task_create function creates a new task from parent_task and returns the name of the new task in child_task. The child task acquires shared or copied parts of the parent's address space (see vm_inherit). The child task initially contains no threads. The child task inherits the parent's security ID.

The child task receives the following "special" ports, which are created or copied for it at task creation:

[task-self send right]
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.

[bootstrap send right]
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 task_set_special_port to change this port.

[host-self send right]
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.

[ledger send rights]
The ports naming the ledgers from which the task draws its resources.

The child task also inherits the following ports:

[sample send right]
The port to which PC sampling messages are to be sent.

[exception send rights]
Ports to which exception messages are sent.

[registered send rights]
Ports to system services.

NOTES

The ledgers functionality mentioned above is not currently implemented.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create_security_token, task_resume, task_set_special_port, task_suspend, task_terminate, task_threads, thread_create, thread_resume, vm_inherit, task_sample, task_set_exception_ports, mach_ports_register, norma_task_create, host_security_set_task_token. \ No newline at end of file +

task_create

+
+

+Function - Create a new task. +

SYNOPSIS

+
+kern_return_t   task_create
+                (task_t                             parent_task,
+                 ledger_port_array_t                    ledgers,
+                 int                               ledger_count,
+                 boolean_t                       inherit_memory,
+                 task_t                              child_task);
+
+

PARAMETERS

+
+

+

parent_task +
+[in task send right] +The port for the task from which to draw the child +task's port rights and address space. +

+

ledgers +
+[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. +

+

ledger_count +
+[in scalar] +The number of ledger ports in the ledgers array. +

+

inherit_memory +
+[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. +

+

child_task +
+[out task send right] +The kernel-assigned port for the new task. +
+

DESCRIPTION

+

+The task_create function creates a new task from parent_task +and returns the name of the new task in child_task. +The child task acquires shared or copied parts of the parent's address space +(see vm_inherit). The child task initially +contains no threads. The child task inherits the parent's security ID. +

+The child task receives the following "special" ports, which are created or +copied for it at task creation: +

+
[task-self send right] +
+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. +

+

[bootstrap send right] +
+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 +task_set_special_port to change this port. +

+

[host-self send right] +
+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. +

+

[ledger send rights] +
+The ports naming the ledgers from which the task draws +its resources. +
+

+The child task also inherits the following ports: +

+
[sample send right] +
+The port to which PC sampling messages are to be sent. +

+

[exception send rights] +
+Ports to which exception messages are sent. +

+

[registered send rights] +
+Ports to system services. +
+

NOTES

+

+The ledgers functionality mentioned above is not +currently implemented. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_create_security_token, +task_resume, +task_set_special_port, +task_suspend, +task_terminate, +task_threads, +thread_create, +thread_resume, +vm_inherit, +task_sample, +task_set_exception_ports, +mach_ports_register, +norma_task_create, +host_security_set_task_token. 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 @@ -

task_get_assignment

Function - Return the processor set to which a task is assigned.

SYNOPSIS

kern_return_t   task_get_assignment
                (task_t                                    task,
                 processor_set_name_t             processor_set);

PARAMETERS

task
[in task send right] The port for the task whose assignment is desired.
processor_set
[out processor-set-name send right] The name port for the processor set into which the task is assigned.

DESCRIPTION

The task_get_assignment function returns the name port to the processor set to which task is currently assigned. This port can only be used to obtain information about the processor set.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_assign, task_assign_default, processor_set_create, processor_set_info, thread_assign. \ No newline at end of file +

task_get_assignment

+
+

+Function - Return the processor set to which a task is assigned. +

SYNOPSIS

+
+kern_return_t   task_get_assignment
+                (task_t                                    task,
+                 processor_set_name_t             processor_set);
+
+

PARAMETERS

+
+
task +
+[in task send right] +The port for the task whose assignment is desired. +
processor_set +
+[out processor-set-name send right] +The name port for the processor +set into which the task is assigned. +
+

DESCRIPTION

+

+The task_get_assignment function returns the name port +to the processor set to +which task is currently assigned. This port can only be used to obtain +information about the processor set. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_assign, +task_assign_default, +processor_set_create, +processor_set_info, +thread_assign. 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 @@ -

task_get_emulation_vector

Function - Return an array identifying the target task's user-level system call handlers.

SYNOPSIS

kern_return_t   task_get_emulation_vector
                (task_t                                    task,
                 int                               vector_start,
                 emulation_vector_t            emulation_vector,
                 mach_msg_type_number_t* emulation_vector_count);

PARAMETERS

task
[in task send right] The port for the task for which the system call handler addresses are desired.

vector_start
[out scalar] The syscall number corresponding to the first element of emulation_vector.

emulation_vector
[out pointer to dynamic array of vm_address_t] Pointer to the returned array of routine entrypoints for the system calls starting with syscall number vector_start.

emulation_vector_count
[out scalar] The number of entries filled by the kernel.

DESCRIPTION

The task_get_emulation_vector function returns the user-level syscall handler entrypoint addresses.

NOTES

This interface is machine word length specific because of the virtual addresses in the emulation_vector parameter.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_set_emulation_vector. \ No newline at end of file +

task_get_emulation_vector

+
+

+Function - Return an array identifying the target task's user-level system call handlers. +

SYNOPSIS

+
+kern_return_t   task_get_emulation_vector
+                (task_t                                    task,
+                 int                               vector_start,
+                 emulation_vector_t            emulation_vector,
+                 mach_msg_type_number_t* emulation_vector_count);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The port for the task for which the system call +handler addresses are desired. +

+

vector_start +
+[out scalar] +The syscall number corresponding to the first element of +emulation_vector. +

+

emulation_vector +
+[out pointer to dynamic array of vm_address_t] +Pointer to the returned +array of routine entrypoints for the system calls starting with syscall +number vector_start. +

+

emulation_vector_count +
+[out scalar] +The number of entries filled by the kernel. +
+

DESCRIPTION

+

+The task_get_emulation_vector function returns the +user-level syscall handler entrypoint addresses. +

NOTES

+

+This interface is machine word length specific because of the +virtual addresses in the emulation_vector parameter. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_set_emulation_vector. 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 @@ -

task_get_exception_ports

Function - Return send rights to the target task's exception ports.

SYNOPSIS

kern_return_t   task_get_exception_ports
                (task_t                                    task,
                 exception_mask_t               exception_types,
                 exception_mask_array_t     old_exception_masks,
                 old_exception_masks        old_exception_count,
                 exception_port_array_t     old_exception_ports,
                 exception_behavior_array_t       old_behaviors,
                 exception_flavor_array_t           old_flavors);

PARAMETERS

task
[in task send right] The task for which to return the exception ports.

exception_types
[in scalar] A flag word indicating the types of exceptions for which the exception ports are desired:

EXC_MASK_BAD_ACCESS
Could not access memory.

EXC_MASK_BAD_INSTRUCTION
Instruction failed. Illegal or undefined instruction or operand.

EXC_MASK_ARITHMETIC
Arithmetic exception

EXC_MASK_EMULATION
Emulation instruction. Emulation support instruction encountered.

EXC_MASK_SOFTWARE
Software generated exception.

EXC_MASK_BREAKPOINT
Trace, breakpoint, etc.

EXC_MASK_SYSCALL
System call requested.

EXC_MASK_MACH_SYSCALL
System call with a number in the Mach call range requested.

EXC_MASK_RPC_ALERT
Exceptional condition encountered during execution of RPC.

old_exception_masks
[out array of exception_mask_t] An array, each element being a mask specifying for which exception types the corresponding element of the other arrays apply.

old_exception_count
[pointer to in/out scalar] On input, the maximum size of the array buffers; on output, the number of returned sets returned.

old_exception_ports
[out array of exception send rights] The returned exception ports.

old_behaviors
[out array of exception_behavior_t] The type of exception message to be sent. Defined types are:

EXCEPTION_DEFAULT
Send a catch_exception_raise message including the thread identity.

EXCEPTION_STATE
Send a catch_exception_raise_state message including the thread state.

EXCEPTION_STATE_IDENTITY
Send a catch_exception_raise_state_identity message including the thread identity and state.

old_flavors
[out array of thread_state_flavor_t] The type of state to be sent with the exception message. These types are defined in <mach/thread_states.h>.

DESCRIPTION

The task_get_exception_ports 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 for each unique set of in effect for the task where the exception type mask indicates for which exception types the other values apply.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_task_self, thread_get_exception_ports, task_set_exception_ports, task_swap_exception_ports, thread_create, thread_set_exception_ports, thread_swap_exception_ports, catch_exception_raise. \ No newline at end of file +

task_get_exception_ports

+
+

+Function - Return send rights to the target task's exception ports. +

SYNOPSIS

+
+kern_return_t   task_get_exception_ports
+                (task_t                                    task,
+                 exception_mask_t               exception_types,
+                 exception_mask_array_t     old_exception_masks,
+                 old_exception_masks        old_exception_count,
+                 exception_port_array_t     old_exception_ports,
+                 exception_behavior_array_t       old_behaviors,
+                 exception_flavor_array_t           old_flavors);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task for which to return the exception ports. +

+

exception_types +
+[in scalar] +A flag word indicating the types of exceptions for which the +exception ports are desired: +
+

+

EXC_MASK_BAD_ACCESS +
+Could not access memory. +

+

EXC_MASK_BAD_INSTRUCTION +
+Instruction failed. Illegal or undefined instruction or operand. +

+

EXC_MASK_ARITHMETIC +
+Arithmetic exception +

+

EXC_MASK_EMULATION +
+Emulation instruction. Emulation support instruction +encountered. +

+

EXC_MASK_SOFTWARE +
+Software generated exception. +

+

EXC_MASK_BREAKPOINT +
+Trace, breakpoint, etc. +

+

EXC_MASK_SYSCALL +
+System call requested. +

+

EXC_MASK_MACH_SYSCALL +
+System call with a number in the Mach call range requested. +

+

EXC_MASK_RPC_ALERT +
+Exceptional condition encountered during execution of RPC. +
+

+

old_exception_masks +
+[out array of exception_mask_t] +An array, each element being a mask +specifying for which exception types the corresponding element of the +other arrays apply. +

+

old_exception_count +
+[pointer to in/out scalar] +On input, the maximum size of the array +buffers; on output, the number of returned sets returned. +

+

old_exception_ports +
+[out array of exception send rights] +The returned exception ports. +

+

old_behaviors +
+[out array of exception_behavior_t] +The type of exception message to +be sent. Defined types are: +
+

+

EXCEPTION_DEFAULT +
+Send a catch_exception_raise message including the thread identity. +

+

EXCEPTION_STATE +
+Send a catch_exception_raise_state message including the +thread state. +

+

EXCEPTION_STATE_IDENTITY +
+Send a catch_exception_raise_state_identity message +including the thread identity and state. +
+

+

old_flavors +
+[out array of thread_state_flavor_t] +The type of state to be sent with +the exception message. These types are defined in <mach/thread_states.h>. +
+

DESCRIPTION

+

+The task_get_exception_ports 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 for each +unique set of in effect for +the task where the +exception type mask indicates for which exception types the other values apply. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_task_self, +thread_get_exception_ports, +task_set_exception_ports, +task_swap_exception_ports, +thread_create, +thread_set_exception_ports, +thread_swap_exception_ports, +catch_exception_raise. 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 @@ -

task_get_special_port

Function - Return a send write to the indicated special port.

SYNOPSIS

kern_return_t   task_get_special_port
                (task_t                                    task,
                 int                                 which_port,
                 task                              special_port);


Macro Forms:


kern_return_t   task_get_bootstrap_port
                (task_t                                    task,
                 task                              special_port);


kern_return_t   task_get_kernel_port
                (task_t                                    task,
                 task                              special_port);


kern_return_t   task_get_host_name_port
                (task_t                                    task,
                 task                              special_port);

PARAMETERS

task
[in task send right] The port for the task for which to return the port's send right.

which_port
[in scalar] The special port for which the send right is requested. Valid values are:

TASK_KERNEL_PORT
[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 mach_task_self.

TASK_BOOTSTRAP_PORT
[bootstrap send right] The task's bootstrap port. Used to send messages requesting return of other system service ports.

TASK_HOST_NAME_PORT
[host-self send right] The port used to request information of the containing host. This is the port returned by mach_host_self.

TASK_WIRED_LEDGER_PORT
[ledger send right] The port naming the source from which this task draws its wired kernel memory.

TASK_PAGED_LEDGER_PORT
[ledger send right] The port naming the source from which this task draws its default memory managed memory.

special_port
[out task-special send right] The returned value for the port.

DESCRIPTION

The task_get_special_port function returns a send right for a special port belonging to task.

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 mach_msg function, however, any task can pass a send right for its kernel port to another task.

NOTES

The current implementation does not support the TASK_HOST_NAME_PORT features associated with this interface.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_task_self, task_create, task_set_special_port, thread_get_special_port, thread_set_special_port, mach_host_self. \ No newline at end of file +

task_get_special_port

+
+

+Function - Return a send write to the indicated special port. +

SYNOPSIS

+
+kern_return_t   task_get_special_port
+                (task_t                                    task,
+                 int                                 which_port,
+                 task                              special_port);
+
+
+Macro Forms:
+
+
+kern_return_t   task_get_bootstrap_port
+                (task_t                                    task,
+                 task                              special_port);
+
+
+kern_return_t   task_get_kernel_port
+                (task_t                                    task,
+                 task                              special_port);
+
+
+kern_return_t   task_get_host_name_port
+                (task_t                                    task,
+                 task                              special_port);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The port for the task for which to return the port's +send right. +

+

which_port +
+[in scalar] +The special port for which the send right is requested. Valid +values are: +
+

+

TASK_KERNEL_PORT +
+[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 mach_task_self. +

+

TASK_BOOTSTRAP_PORT +
+[bootstrap send right] The task's bootstrap port. Used to send +messages requesting return of other system service ports. +

+

TASK_HOST_NAME_PORT +
+[host-self send right] The port used to request information of +the containing host. This is the port returned by +mach_host_self. +

+

TASK_WIRED_LEDGER_PORT +
+[ledger send right] The port naming the source from which +this task draws its wired kernel memory. +

+

TASK_PAGED_LEDGER_PORT +
+[ledger send right] The port naming the source from which +this task draws its default memory managed memory. +
+

+

special_port +
+[out task-special send right] +The returned value for the port. +
+

DESCRIPTION

+

+The task_get_special_port function returns a send right +for a special port belonging to task. +

+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 mach_msg function, however, +any task can pass a send right for its kernel port to another task. +

NOTES

+

+The current implementation does not support the TASK_HOST_NAME_PORT +features associated with this interface. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_task_self, +task_create, +task_set_special_port, +thread_get_special_port, +thread_set_special_port, +mach_host_self. 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 @@ -

task_info

Function - Return per-task information according to specified flavor.

SYNOPSIS

kern_return_t   task_info
                (task_t                                    task,
                 task_flavor_t                           flavor,
                 task_info_t                          task_info,
                 mach_msg_type_number_t         task_info_count);

PARAMETERS

task
[in task send right] The port for the task for which the information is to be returned.

flavor
[in scalar] The type of information to be returned. Valid values are:

TASK_BASIC_INFO
Returns basic information about the task, such as the task's suspend count and number of resident pages. The structure returned is task_basic_info.

TASK_THREAD_TIMES_INFO
Returns system and user space run-times for live threads. The structure returned is task_thread_times_info.

TASK_SCHED_FIFO_INFO
Returns default FIFO scheduling policy attributes to be assigned to new threads. The structure returned is policy_fifo_base.

TASK_SCHED_RR_INFO
Returns default round-robin scheduling policy attributes to be assigned to new threads. The structure returned is policy_rr_base.

TASK_SCHED_TIMESHARE_INFO
Returns default timeshare scheduling policy attributes to be assigned to new threads. The structure returned is policy_timeshare_base.

TASK_SECURITY_TOKEN
Returns the security token for the task. The value returned is of type security_token_t.

TASK_AUDIT_TOKEN
Returns the security token for the task. The value returned is of type audit_token_t.

TASK_USER_DATA
Returns user-specified information previously established via the task_set_info interface. The structure returned is task_user_data.

task_info
[out structure] Information about the specified task.

task_info_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The task_info function returns an information structure of type flavor.

NOTES

At any given time, a task has one default scheduling policy assigned to it (as returned by TASK_BASIC_INFO). As such, only one of the scheduling flavors will return valid information.

RETURN VALUES

KERN_INVALID_POLICY
A request was made for the default scheduling policy attributes for the task but the requested policy is not the task's default policy.

RELATED INFORMATION

Functions: task_get_special_port, task_set_special_port, task_set_info, task_threads, thread_info, thread_get_state, thread_set_state.

Data Structures: task_basic_info, policy_timeshare_info, policy_fifo_info, policy_rr_info, task_thread_times_info. \ No newline at end of file +

task_info

+
+

+Function - Return per-task information according to specified flavor. +

SYNOPSIS

+
+kern_return_t   task_info
+                (task_t                                    task,
+                 task_flavor_t                           flavor,
+                 task_info_t                          task_info,
+                 mach_msg_type_number_t         task_info_count);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The port for the task for which the information is to +be returned. +

+

flavor +
+[in scalar] +The type of information to be returned. Valid values are: +
+

+

TASK_BASIC_INFO +
+Returns basic information about the task, such as the task's +suspend count and number of resident pages. The structure +returned is task_basic_info. +

+

TASK_THREAD_TIMES_INFO +
+Returns system and user space run-times for live threads. The +structure returned is task_thread_times_info. +

+

TASK_SCHED_FIFO_INFO +
+Returns default FIFO scheduling policy attributes to be +assigned to new threads. The structure returned is policy_fifo_base. +

+

TASK_SCHED_RR_INFO +
+Returns default round-robin scheduling policy attributes to be +assigned to new threads. The structure returned is +policy_rr_base. +

+

TASK_SCHED_TIMESHARE_INFO +
+Returns default timeshare scheduling policy attributes to be +assigned to new threads. The structure returned is +policy_timeshare_base. +

+

TASK_SECURITY_TOKEN +
+Returns the security token for the task. The value returned is of +type security_token_t. +

+

TASK_AUDIT_TOKEN +
+Returns the security token for the task. The value returned is of +type audit_token_t. +

+

TASK_USER_DATA +
+Returns user-specified information previously established via the +task_set_info interface. The structure returned is +task_user_data. +
+

+

task_info +
+[out structure] +Information about the specified task. +

+

task_info_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The task_info function returns an information structure +of type flavor. +

NOTES

+

+At any given time, a task has one default scheduling policy assigned to it (as +returned by TASK_BASIC_INFO). As such, only one of the scheduling flavors +will return valid information. +

RETURN VALUES

+
+

+

KERN_INVALID_POLICY +
+A request was made for the default scheduling policy attributes for the +task but the requested policy is not the task's default policy. +
+

RELATED INFORMATION

+

+Functions: +task_get_special_port, +task_set_special_port, +task_set_info, +task_threads, +thread_info, +thread_get_state, +thread_set_state. +

+Data Structures: +task_basic_info, +policy_timeshare_info, +policy_fifo_info, +policy_rr_info, +task_thread_times_info. 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 @@ -

task_policy

Function - Set target task's default scheduling policy state.

SYNOPSIS

kern_return_t   task_policy
                (task_t                                    task,
                 policy_t                                policy,
                 policy_base_t                             base,
                 base                                base_count,
                 boolean_t                            set_limit,
                 boolean_t                       change_threads);

PARAMETERS

task
[in task send right] The port for the task whose scheduling attributes are to be set.
policy
[in scalar] Default policy. The values currently defined are POLICY_TIMESHARE, POLICY_RR (round robin) and POLICY_FIFO (firstin, first-out).
base
[pointer to in structure] Base scheduling policy data, policy_fifo_base, policy_rr_base or policy_timeshare_base.
base_count
[in scalar] The size of the buffer (in natural-sized units).
set_limit
[in scalar] True if the scheduling limits for the task should be restricted to allow no more service than specified by base.
change_threads
[in scalar] True if the attributes (and limits, if set_limit is true) of existing threads within the task should also be changed.

DESCRIPTION

The task_policy function sets the default scheduling attributes for task. 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 change_threads is TRUE. At no time will a thread ever have scheduling attributes that exceed the thread's limits.

RETURN VALUES

KERN_INVALID_POLICY
The processor set does not currently enable policy.
KERN_POLICY_LIMIT
The specified scheduling attributes exceeds the thread's limits.

RELATED INFORMATION

Functions: thread_policy, thread_set_policy, task_set_policy, processor_set_policy_control.

Data Structures: policy_fifo_info, policy_rr_info, policy_timeshare_info. \ No newline at end of file +

task_policy

+
+

+Function - Set target task's default scheduling policy state. +

SYNOPSIS

+
+kern_return_t   task_policy
+                (task_t                                    task,
+                 policy_t                                policy,
+                 policy_base_t                             base,
+                 base                                base_count,
+                 boolean_t                            set_limit,
+                 boolean_t                       change_threads);
+
+

PARAMETERS

+
+
task +
+[in task send right] +The port for the task whose scheduling attributes +are to be set. +
policy +
+[in scalar] +Default policy. The values currently defined are POLICY_TIMESHARE, +POLICY_RR (round robin) and POLICY_FIFO (firstin, first-out). +
base +
+[pointer to in structure] +Base scheduling policy data, policy_fifo_base, +policy_rr_base or policy_timeshare_base. +
base_count +
+[in scalar] +The size of the buffer (in natural-sized units). +
set_limit +
+[in scalar] +True if the scheduling limits for the task should be restricted +to allow no more service than specified by base. +
change_threads +
+[in scalar] +True if the attributes (and limits, if set_limit is true) of +existing threads within the task should also be changed. +
+

DESCRIPTION

+

+The task_policy function sets the default scheduling +attributes for task. 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 +change_threads is TRUE. At no time will a thread ever have +scheduling attributes that exceed the thread's limits. +

RETURN VALUES

+
+
KERN_INVALID_POLICY +
+The processor set does not currently enable policy. +
KERN_POLICY_LIMIT +
+The specified scheduling attributes exceeds the thread's limits. +
+

RELATED INFORMATION

+

+Functions: +thread_policy, +thread_set_policy, +task_set_policy, +processor_set_policy_control. +

+Data Structures: +policy_fifo_info, +policy_rr_info, +policy_timeshare_info. 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 @@ -

task_resume

Function - Decrement the target task's suspend count.

SYNOPSIS

kern_return_t   task_resume
                (task_t         task);

PARAMETERS

task
[in task send right] The port to the task to be resumed.

DESCRIPTION

The task_resume function decrements the suspend count for task. 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.

NOTES

An attempt to lower the suspend count below zero is ignored.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create, task_info, task_suspend, task_terminate, thread_info, thread_resume, thread_suspend. \ No newline at end of file +

task_resume

+
+

+Function - Decrement the target task's suspend count. +

SYNOPSIS

+
+kern_return_t   task_resume
+                (task_t         task);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The port to the task to be resumed. +
+

DESCRIPTION

+

+The task_resume function decrements the suspend count +for task. 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. +

NOTES

+

+An attempt to lower the suspend count below zero is ignored. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_create, +task_info, +task_suspend, +task_terminate, +thread_info, +thread_resume, +thread_suspend. 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 @@ -

task_sample

Function - Sample the target task's thread program counters periodically.

SYNOPSIS

kern_return_t   task_sample
                (task_t                             sample_task,
                 mach_port_make_send_t               reply_port);

PARAMETERS

sample_task
[in task send right] Port for the task whose threads' PC are to be sampled.

reply_port
[in sample receive (to be converted to send) right] Port to which PC sample buffers are sent. A value of MACH_PORT_NULL stops PC sampling for the task.

DESCRIPTION

The task_sample function causes the program counter (PC) of the specified sample_task (actually, all of the threads within sample_task) 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 reply_port in receive_samples messages.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: thread_sample, receive_samples. \ No newline at end of file +

task_sample

+
+

+Function - Sample the target task's thread program counters periodically. +

SYNOPSIS

+
+kern_return_t   task_sample
+                (task_t                             sample_task,
+                 mach_port_make_send_t               reply_port);
+
+

PARAMETERS

+
+

+

sample_task +
+[in task send right] +Port for the task whose threads' PC are to be +sampled. +

+

reply_port +
+[in sample receive (to be converted to send) right] +Port to which PC sample buffers are sent. A value of MACH_PORT_NULL +stops PC sampling for the task. +
+

DESCRIPTION

+

+The task_sample function causes the program counter (PC) of the +specified sample_task (actually, all of the threads within +sample_task) 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 reply_port in receive_samples messages. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +thread_sample, +receive_samples. 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 @@ -

task_set_emulation

Function - Establish a user-level handler for a system call.

SYNOPSIS

kern_return_t   task_set_emulation
                (task_t                                    task,
                 vm_address_t                  routine_entry_pt,
                 int                             syscall_number);

PARAMETERS

task
[in task port] The port for the task for which to establish the system call handler.

routine_entry_pt
[in scalar] The address within the task of the handler for this particular system call.

syscall_number
[in scalar] The number of the system call to be handled by this handler.

DESCRIPTION

The task_set_emulation 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.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_set_emulation_vector, task_get_emulation_vector. \ No newline at end of file +

task_set_emulation

+
+

+Function - Establish a user-level handler for a system call. +

SYNOPSIS

+
+kern_return_t   task_set_emulation
+                (task_t                                    task,
+                 vm_address_t                  routine_entry_pt,
+                 int                             syscall_number);
+
+

PARAMETERS

+
+

+

task +
+[in task port] The port for the task for which to establish the system call handler. +

+

routine_entry_pt +
+[in scalar] The address within the task of the handler for this particular system call. +

+

syscall_number +
+[in scalar] The number of the system call to be handled by this handler. +
+

DESCRIPTION

+

+The task_set_emulation 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. +

NOTES

+

+This interface is machine word length specific because of the virtual +address parameter. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_set_emulation_vector, +task_get_emulation_vector. 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 @@ -

task_set_emulation_vector

Function - Establish the target task's user-level system call handlers.

SYNOPSIS

kern_return_t   task_set_emulation_vector
                (task_t                                    task,
                 int                               vector_start,
                 emulation_vector_t            emulation_vector,
                 mach_msg_type_number_t  emulation_vector_count);

PARAMETERS

task
[in task send right] The port for the task for which to establish the system call handler.

vector_start
[in scalar] The syscall number corresponding to the first element of emulation_vector.

emulation_vector
[pointer to in array of vm_address_t] An array of routine entrypoints for the system calls starting with syscall number vector_start.

emulation_vector_count
[in scalar] The number of elements in emulation_vector.

DESCRIPTION

The task_set_emulation_vector 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.

These emulation handler addresses are inherited by child processes.

NOTES

This interface is machine word length specific because of the virtual addresses in the emulation_vector parameter.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_get_emulation_vector. \ No newline at end of file +

task_set_emulation_vector

+
+

+Function - Establish the target task's user-level system call handlers. +

SYNOPSIS

+
+kern_return_t   task_set_emulation_vector
+                (task_t                                    task,
+                 int                               vector_start,
+                 emulation_vector_t            emulation_vector,
+                 mach_msg_type_number_t  emulation_vector_count);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The port for the task for which to establish the +system call handler. +

+

vector_start +
+[in scalar] +The syscall number corresponding to the first element of +emulation_vector. +

+

emulation_vector +
+[pointer to in array of vm_address_t] +An array of routine entrypoints +for the system calls starting with syscall number vector_start. +

+

emulation_vector_count +
+[in scalar] +The number of elements in emulation_vector. +
+

DESCRIPTION

+

+The task_set_emulation_vector 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. +

+These emulation handler addresses are inherited by child processes. +

NOTES

+

+This interface is machine word length specific because of the +virtual addresses +in the emulation_vector parameter. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_get_emulation_vector. 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 @@ -

task_set_exception_ports

Function - Set target task's exception ports.

SYNOPSIS

kern_return_t   task_set_exception_ports
                (task_t                                    task,
                 exception_mask_t               exception_types,
                 mach_port_t                     exception_port,
                 exception_behavior_t                  behavior,
                 thread_state_flavor_t                   flavor);

PARAMETERS

task
[in task send right] The task for which to set the ports.

exception_types
[in scalar] A flag word indicating the types of exceptions for which the exception port applies:

EXC_MASK_BAD_ACCESS
Could not access memory.

EXC_MASK_BAD_INSTRUCTION
Instruction failed. Illegal or undefined instruction or operand.

EXC_MASK_ARITHMETIC
Arithmetic exception

EXC_MASK_EMULATION
Emulation instruction. Emulation support instruction encountered.

EXC_MASK_SOFTWARE
Software generated exception.

EXC_MASK_BREAKPOINT
Trace, breakpoint, etc.

EXC_MASK_SYSCALL
System call requested.

EXC_MASK_MACH_SYSCALL
System call with a number in the Mach call range requested.

EXC_MASK_RPC_ALERT
Exceptional condition encountered during execution of RPC.

exception_port
[in exception send right] The exception port for all selected exception types.

behavior
[in scalar] The type of exception message to be sent. Defined types are:

EXCEPTION_DEFAULT
Send a catch_exception_raise message including the thread identity.

EXCEPTION_STATE
Send a catch_exception_raise_state message including the thread state.

EXCEPTION_STATE_PROTECTED
Send a catch_exception_raise_state message including the thread state. Mark the exception port (and associated exceptions) as protected.

EXCEPTION_STATE_IDENTITY
Send a catch_exception_raise_state_identity message including the thread identity and state.

EXCEPTION_STATE_IDENTITY_PROTECTED
Send a catch_exception_raise_state_identity message including the thread identity and state. Mark the exception port (and associated exceptions) as protected.

flavor
[in scalar] The type of state to be sent with the exception message. These types are defined in <mach/thread_states.h>.

DESCRIPTION

The task_set_exception_ports function sets 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.

NOTES

If the value of the EXC_MACH_SYSCALL 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_task_self, task_get_exception_ports, task_swap_exception_ports, thread_set_exception_ports, thread_create, thread_get_exception_ports, thread_swap_exception_ports, catch_exception_raise, thread_abort. \ No newline at end of file +

task_set_exception_ports

+
+

+Function - Set target task's exception ports. +

SYNOPSIS

+
+kern_return_t   task_set_exception_ports
+                (task_t                                    task,
+                 exception_mask_t               exception_types,
+                 mach_port_t                     exception_port,
+                 exception_behavior_t                  behavior,
+                 thread_state_flavor_t                   flavor);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task for which to set the ports. +

+

exception_types +
+[in scalar] +A flag word indicating the types of exceptions for which the +exception port applies: +
+

+

EXC_MASK_BAD_ACCESS +
+Could not access memory. +

+

EXC_MASK_BAD_INSTRUCTION +
+Instruction failed. Illegal or undefined instruction or operand. +

+

EXC_MASK_ARITHMETIC +
+Arithmetic exception +

+

EXC_MASK_EMULATION +
+Emulation instruction. Emulation support instruction +encountered. +

+

EXC_MASK_SOFTWARE +
+Software generated exception. +

+

EXC_MASK_BREAKPOINT +
+Trace, breakpoint, etc. +

+

EXC_MASK_SYSCALL +
+System call requested. +

+

EXC_MASK_MACH_SYSCALL +
+System call with a number in the Mach call range requested. +

+

EXC_MASK_RPC_ALERT +
+Exceptional condition encountered during execution of RPC. +
+

+

exception_port +
+[in exception send right] +The exception port for all selected exception +types. +

+

behavior +
+[in scalar] +The type of exception message to be sent. Defined types are: +
+

+

EXCEPTION_DEFAULT +
+Send a catch_exception_raise message including the thread +identity. +

+

EXCEPTION_STATE +
+Send a catch_exception_raise_state message including the +thread state. +

+

EXCEPTION_STATE_PROTECTED +
+Send a catch_exception_raise_state message including the +thread state. Mark the exception port (and associated +exceptions) as protected. +

+

EXCEPTION_STATE_IDENTITY +
+Send a catch_exception_raise_state_identity message +including the thread identity and state. +

+

EXCEPTION_STATE_IDENTITY_PROTECTED +
+Send a catch_exception_raise_state_identity message +including the thread identity and state. Mark the exception port +(and associated exceptions) as protected. +
+

+

flavor +
+[in scalar] +The type of state to be sent with the exception message. +These types are defined in <mach/thread_states.h>. +
+

DESCRIPTION

+

+The task_set_exception_ports function sets 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. +

NOTES

+

+If the value of the EXC_MACH_SYSCALL 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_task_self, +task_get_exception_ports, +task_swap_exception_ports, +thread_set_exception_ports, +thread_create, +thread_get_exception_ports, +thread_swap_exception_ports, +catch_exception_raise, +thread_abort. 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 @@ -

task_set_info

Function - Set task-specific information state.

SYNOPSIS

#include<task_info.h>

kern_return_t   task_set_info
                (task_t                             target_task,
                 task_flavor_t                           flavor,
                 task_info_t                          task_info);

PARAMETERS

target_task
The task whose information is to be set.

flavor
Specifies the type of information to be set. Currently the interface supports the setting of a single flavor: TASK_USER_DATA.

task_info
Specifies the information to be set.

DESCRIPTION

The task_set_info interface provides the caller with the means to set the target task's user_data field. This field may be used to specify arbitrarily task-specific data.

NOTES

Currently, this interface is used exclusively to provide freshly colocated user tasks with the short-circuited RPC glue vector.

RETURN VALUES

Only generic values apply.

RELATED INFORMATION

\ No newline at end of file +

task_set_info

+
+

+Function - Set task-specific information state. +

SYNOPSIS

+
+#include<task_info.h>
+
+kern_return_t   task_set_info
+                (task_t                             target_task,
+                 task_flavor_t                           flavor,
+                 task_info_t                          task_info);
+
+

PARAMETERS

+
+

+

target_task +
+The task whose information is to be set. +

+

flavor +
+Specifies the type of information to be set. Currently the interface +supports the setting of a single flavor: +TASK_USER_DATA. +

+

task_info +
+Specifies the information to be set. +
+

DESCRIPTION

+

+The task_set_info interface provides the caller with +the means to set the target task's user_data field. This +field may be used to specify arbitrarily task-specific data. +

NOTES

+

+Currently, this interface is used exclusively to provide freshly +colocated user tasks with the short-circuited RPC glue vector. +

RETURN VALUES

+

+Only generic values apply. +

RELATED INFORMATION

+

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 @@ -

task_set_policy

Function - Set target task's default scheduling policy state. (Protected Interface.)

SYNOPSIS

kern_return_t   task_set_policy
                (task_t                                    task,
                 processor_set_t                  processor_set,
                 policy_t                                policy,
                 policy_base_t                             base,
                 mach_msg_type_number_t              base_count,
                 policy_limit_t                           limit,
                 mach_msg_type_number_t             limit_count,
                 boolean_t                       change_threads);

PARAMETERS

task
[in task send right] The task whose scheduling policy is to be set.
processor_set
[in processor-set-control send right] The control port for the processor set to which the task is currently assigned.
policy
[in scalar] Policy to be set. The values currently defined are POLICY_TIMESHARE, POLICY_RR (round robin) and POLICY_FIFO (firstin, first-out).
base
[pointer to in structure] Base policy specific data, policy_fifo_base, policy_rr_base or policy_timeshare_base.
base_count
[in scalar] The size of the buffer (in natural-sized units).
limit
[pointer to in structure] Policy specific limits, policy_fifo_limit, policy_rr_limit or policy_timeshare_limit.
limit_count
[in scalar] The size of the buffer (in natural-sized units).
change_threads
[in scalar] True if the scheduling attributes for all contained threads should be changed as well.

DESCRIPTION

The task_set_policy function sets the scheduling attributes, both base and limit, for task. policy may be any policy implemented by the processor set whether or not it is enabled.

RETURN VALUES

KERN_INVALID_PROCESSOR_SET
processor_set is not the task's processor set control port.

RELATED INFORMATION

Functions: processor_set_policy_control, thread_policy, thread_set_policy, task_policy.

Data Structures: policy_fifo_info, policy_rr_info, policy_timeshare_info. \ No newline at end of file +

task_set_policy

+
+

+Function - Set target task's default scheduling policy state. (Protected Interface.) +

SYNOPSIS

+
+kern_return_t   task_set_policy
+                (task_t                                    task,
+                 processor_set_t                  processor_set,
+                 policy_t                                policy,
+                 policy_base_t                             base,
+                 mach_msg_type_number_t              base_count,
+                 policy_limit_t                           limit,
+                 mach_msg_type_number_t             limit_count,
+                 boolean_t                       change_threads);
+
+

PARAMETERS

+
+
task +
+[in task send right] +The task whose scheduling policy is to be set. +
processor_set +
+[in processor-set-control send right] +The control port for the processor +set to which the task is currently assigned. +
policy +
+[in scalar] +Policy to be set. The values currently defined are POLICY_TIMESHARE, +POLICY_RR (round robin) and POLICY_FIFO (firstin, first-out). +
base +
+[pointer to in structure] +Base policy specific data, policy_fifo_base, +policy_rr_base or policy_timeshare_base. +
base_count +
+[in scalar] +The size of the buffer (in natural-sized units). +
limit +
+[pointer to in structure] +Policy specific limits, policy_fifo_limit, +policy_rr_limit or policy_timeshare_limit. +
limit_count +
+[in scalar] +The size of the buffer (in natural-sized units). +
change_threads +
+[in scalar] +True if the scheduling attributes for all contained threads +should be changed as well. +
+

DESCRIPTION

+

+The task_set_policy function sets the scheduling attributes, +both base and limit, for task. +policy may be any policy implemented by the processor set whether or +not it is enabled. +

RETURN VALUES

+
+
KERN_INVALID_PROCESSOR_SET +
+processor_set is not the task's processor set control port. +
+

RELATED INFORMATION

+

+Functions: +processor_set_policy_control, +thread_policy, +thread_set_policy, +task_policy. +

+Data Structures: +policy_fifo_info, +policy_rr_info, +policy_timeshare_info. 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 @@ -

task_set_port_space

Function - Set the size of the target task's port name space table.

SYNOPSIS

kern_return_t   task_set_port_space
                (task_t                                    task,
                 int                              table_entries);

PARAMETERS

task
[in send right] The port referencing the task whose port name space is to be set.

table_entries
[in scalar] The number of entries in the port name space table.

DESCRIPTION

The task_set_port_space function preallocates the specified number of entries in the specified task's IPC name space.

RETURN VALUES

KERN_NO_SPACE
The requested table size exceeds the maximum allowable table size.

RELATED INFORMATION

Functions: mach_port_allocate. \ No newline at end of file +

task_set_port_space

+
+

+Function - Set the size of the target task's port name space table. +

SYNOPSIS

+
+kern_return_t   task_set_port_space
+                (task_t                                    task,
+                 int                              table_entries);
+
+

PARAMETERS

+
+

+

task +
+[in send right] The port referencing the task whose port name space is +to be set. +

+

table_entries +
+[in scalar] The number of entries in the port name space table. +
+

DESCRIPTION

+

+The task_set_port_space function preallocates the specified number of +entries in the specified task's IPC name space. +

RETURN VALUES

+
+

+

KERN_NO_SPACE +
+The requested table size exceeds the maximum allowable table size. +
+

RELATED INFORMATION

+

+Functions: +mach_port_allocate. 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 @@ -

task_set_special_port

Function - Set the indicated special port.

SYNOPSIS

kern_return_t   task_set_special_port
                (task_t                                    task,
                 int                                 which_port,
                 mach_port_t                       special_port);


Macro forms:


kern_return_t   task_set_bootstrap_port
                (task_t                                    task,
                 int                                 which_port,
                 mach_port_t                       special_port);


kern_return_t   task_set_kernel_port
                (task_t                                    task,
                 int                                 which_port,
                 mach_port_t                       special_port);


kern_return_t   task_set_host_name_port
                (task_t                                    task,
                 mach_port_t                       special_port);

PARAMETERS

task
[in task send right] The port for the task for which to set the port.

which_port
[in scalar] The special port to be set. Valid values are:

TASK_BOOTSTRAP_PORT
[bootstrap send right] The task's bootstrap port. Used to send messages requesting return of other system service ports.

TASK_KERNEL_PORT
[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 mach_task_self. 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.

TASK_HOST_NAME_PORT
[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 mach_host_self. 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.

TASK_WIRED_LEDGER_PORT
[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.

TASK_PAGED_LEDGER_PORT
[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.

special_port
[in task-special send right] The value for the port.

DESCRIPTION

The task_set_special_port function sets a special port belonging to task.

NOTES

The current implementation does not support the TASK_HOST_NAME_PORT features associated with this interface.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create, task_get_special_port, mach_task_self, thread_get_special_port, thread_set_special_port, mach_host_self. \ No newline at end of file +

task_set_special_port

+
+

+Function - Set the indicated special port. +

SYNOPSIS

+
+kern_return_t   task_set_special_port
+                (task_t                                    task,
+                 int                                 which_port,
+                 mach_port_t                       special_port);
+
+
+Macro forms:
+
+
+kern_return_t   task_set_bootstrap_port
+                (task_t                                    task,
+                 int                                 which_port,
+                 mach_port_t                       special_port);
+
+
+kern_return_t   task_set_kernel_port
+                (task_t                                    task,
+                 int                                 which_port,
+                 mach_port_t                       special_port);
+
+
+kern_return_t   task_set_host_name_port
+                (task_t                                    task,
+                 mach_port_t                       special_port);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The port for the task for which to set the port. +

+

which_port +
+[in scalar] +The special port to be set. Valid values are: +
+

+

TASK_BOOTSTRAP_PORT +
+[bootstrap send right] The task's bootstrap port. Used to send +messages requesting return of other system service ports. +

+

TASK_KERNEL_PORT +
+[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 mach_task_self. 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. +

+

TASK_HOST_NAME_PORT +
+[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 mach_host_self. 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. +

+

TASK_WIRED_LEDGER_PORT +
+[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. +

+

TASK_PAGED_LEDGER_PORT +
+[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. +
+

+

special_port +
+[in task-special send right] +The value for the port. +
+

DESCRIPTION

+

+The task_set_special_port function sets a special port +belonging to task. +

NOTES

+

+The current implementation does not support the TASK_HOST_NAME_PORT +features associated with this interface. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_create, +task_get_special_port, +mach_task_self, +thread_get_special_port, +thread_set_special_port, +mach_host_self. 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 @@ -

task_suspend

Function - Suspend the target task.

SYNOPSIS

kern_return_t   task_suspend
                (task_t          task);

PARAMETERS

task
[in task send right] The port for the task to be suspended.

DESCRIPTION

The task_suspend 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.

NOTES

To resume a suspended task and its threads, use task_resume. If the suspend count is greater than one, task_resume must be repeated that number of times.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create, task_info, task_resume, task_terminate, thread_suspend. \ No newline at end of file +

task_suspend

+
+

+Function - Suspend the target task. +

SYNOPSIS

+
+kern_return_t   task_suspend
+                (task_t          task);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The port for the task to be suspended. +
+

DESCRIPTION

+

+The task_suspend 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. +

NOTES

+

+To resume a suspended task and its threads, use task_resume. +If the suspend +count is greater than one, task_resume must be repeated +that number of times. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_create, +task_info, +task_resume, +task_terminate, +thread_suspend. 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 @@ -

task_swap_exception_ports

Function - Set target task's exception ports, returning the previous exception ports.

SYNOPSIS

kern_return_t   task_swap_exception_ports
                (task_t                                    task,
                 exception_mask_t               exception_types,
                 mach_port_t                     exception_port,
                 exception_behavior_t                  behavior,
                 thread_state_flavor_t                   flavor,
                 exception_mask_array_t     old_exception_masks,
                 old_exception_masks        old_exception_count,
                 exception_port_array_t     old_exception_ports,
                 exception_behavior_array_t       old_behaviors,
                 exception_flavor_array_t           old_flavors);

PARAMETERS

task
[in task send right] The task for which to set the ports.

exception_types
[in scalar] A flag word indicating the types of exceptions for which the exception port applies:

EXC_MASK_BAD_ACCESS
Could not access memory.

EXC_MASK_BAD_INSTRUCTION
Instruction failed. Illegal or undefined instruction or operand.

EXC_MASK_ARITHMETIC
Arithmetic exception

EXC_MASK_EMULATION
Emulation instruction. Emulation support instruction encountered.

EXC_MASK_SOFTWARE
Software generated exception.

EXC_MASK_BREAKPOINT
Trace, breakpoint, etc.

EXC_MASK_SYSCALL
System call requested.

EXC_MASK_MACH_SYSCALL
System call with a number in the Mach call range requested.

EXC_MASK_RPC_ALERT
Exceptional condition encountered during execution of RPC.

exception_port
[in exception send right] The exception port for all selected exception types.

behavior
[in scalar] The type of exception message to be sent. Defined types are:

EXCEPTION_DEFAULT
Send a catch_exception_raise message including the thread identity.

EXCEPTION_STATE
Send a catch_exception_raise_state message including the thread state.

EXCEPTION_STATE_PROTECTED
Send a catch_exception_raise_state message including the thread state. Mark the exception port (and associated exceptions) as protected.

EXCEPTION_STATE_IDENTITY
Send a catch_exception_raise_state_identity message including the thread identity and state.

EXCEPTION_STATE_IDENTITY_PROTECTED
Send a catch_exception_raise_state_identity message including the thread identity and state. Mark the exception port (and associated exceptions) as protected.

flavor
[in scalar] The type of state to be sent with the exception message. These types are defined in <mach/thread_states.h>.

old_exception_masks
[out array of exception_mask_t] An array, each element being a mask specifying for which exception types the corresponding element of the other arrays apply.

old_exception_count
[pointer to in/out scalar] On input, the maximum size of the array buffers; on output, the number of returned sets returned.

old_exception_ports
[out array of exception send rights] The returned exception ports.

old_behaviors
[out array of exception_behavior_t] The type of exception message to be sent as with behavior.

old_flavors
[out array of thread_state_flavor_t] The type of state to be sent with the exception message. These types are defined in <mach/thread_states.h>.

DESCRIPTION

The task_swap_exception_ports function sets a specified set of exception ports belonging to task, returning the old set. A task exception port is used when a thread specific exception port returns a non-success reply.

NOTES

If the value of the EXC_MACH_SYSCALL 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_task_self, task_get_exception_ports, task_set_exception_ports, thread_create, thread_get_exception_ports, thread_set_exception_ports, thread_swap_exception_ports, catch_exception_raise, thread_abort. \ No newline at end of file +

task_swap_exception_ports

+
+

+Function - Set target task's exception ports, returning the previous exception ports. +

SYNOPSIS

+
+kern_return_t   task_swap_exception_ports
+                (task_t                                    task,
+                 exception_mask_t               exception_types,
+                 mach_port_t                     exception_port,
+                 exception_behavior_t                  behavior,
+                 thread_state_flavor_t                   flavor,
+                 exception_mask_array_t     old_exception_masks,
+                 old_exception_masks        old_exception_count,
+                 exception_port_array_t     old_exception_ports,
+                 exception_behavior_array_t       old_behaviors,
+                 exception_flavor_array_t           old_flavors);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The task for which to set the ports. +

+

exception_types +
+[in scalar] +A flag word indicating the types of exceptions for which the +exception port applies: +
+

+

EXC_MASK_BAD_ACCESS +
+Could not access memory. +

+

EXC_MASK_BAD_INSTRUCTION +
+Instruction failed. Illegal or undefined instruction or operand. +

+

EXC_MASK_ARITHMETIC +
+Arithmetic exception +

+

EXC_MASK_EMULATION +
+Emulation instruction. Emulation support instruction +encountered. +

+

EXC_MASK_SOFTWARE +
+Software generated exception. +

+

EXC_MASK_BREAKPOINT +
+Trace, breakpoint, etc. +

+

EXC_MASK_SYSCALL +
+System call requested. +

+

EXC_MASK_MACH_SYSCALL +
+System call with a number in the Mach call range requested. +

+

EXC_MASK_RPC_ALERT +
+Exceptional condition encountered during execution of RPC. +
+

+

exception_port +
+[in exception send right] +The exception port for all selected exception +types. +

+

behavior +
+[in scalar] +The type of exception message to be sent. Defined types are: +
+

+

EXCEPTION_DEFAULT +
+Send a catch_exception_raise message including the thread +identity. +

+

EXCEPTION_STATE +
+Send a catch_exception_raise_state message including the +thread state. +

+

EXCEPTION_STATE_PROTECTED +
+Send a catch_exception_raise_state message including the +thread state. Mark the exception port (and associated +exceptions) as protected. +

+

EXCEPTION_STATE_IDENTITY +
+Send a catch_exception_raise_state_identity message +including the thread identity and state. +

+

EXCEPTION_STATE_IDENTITY_PROTECTED +
+Send a catch_exception_raise_state_identity message +including the thread identity and state. Mark the exception port +(and associated exceptions) as protected. +
+

+

flavor +
+[in scalar] +The type of state to be sent with the exception message. +These types are defined in <mach/thread_states.h>. +

+

old_exception_masks +
+[out array of exception_mask_t] +An array, each element being a mask +specifying for which exception types the corresponding element of the +other arrays apply. +

+

old_exception_count +
+[pointer to in/out scalar] +On input, the maximum size of the array +buffers; on output, the number of returned sets returned. +

+

old_exception_ports +
+[out array of exception send rights] +The returned exception ports. +

+

old_behaviors +
+[out array of exception_behavior_t] +The type of exception message to +be sent as with behavior. +

+

old_flavors +
+[out array of thread_state_flavor_t] +The type of state to be sent with +the exception message. These types are defined in <mach/thread_states.h>. +
+

DESCRIPTION

+

+The task_swap_exception_ports function sets a specified +set of exception +ports belonging to task, returning the old set. A task exception +port is used when +a thread specific exception port returns a non-success reply. +

NOTES

+

+If the value of the EXC_MACH_SYSCALL 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_task_self, +task_get_exception_ports, +task_set_exception_ports, +thread_create, +thread_get_exception_ports, +thread_set_exception_ports, +thread_swap_exception_ports, +catch_exception_raise, +thread_abort. 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 @@ -

task_terminate

Function - Terminate the target task and deallocate its resources.

SYNOPSIS

kern_return_t   task_terminate
                (task_t            task);

PARAMETERS

task
[in task send right] The port for the task to be destroyed.

DESCRIPTION

The task_terminate 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create, task_suspend, task_resume, thread_terminate, thread_suspend. \ No newline at end of file +

task_terminate

+
+

+Function - Terminate the target task and deallocate its resources. +

SYNOPSIS

+
+kern_return_t   task_terminate
+                (task_t            task);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The port for the task to be destroyed. +
+

DESCRIPTION

+

+The task_terminate 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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_create, +task_suspend, +task_resume, +thread_terminate, +thread_suspend. 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 @@ -

task_thread_times_info

Structure - Defines thread execution times information for tasks.

SYNOPSIS

struct task_thread_times_info
{
       time_value_t         user_time;
       time_value_t       system_time;
};

typedef struct task_thread_times_info* task_thread_times_info_t;

FIELDS

user_time
Total user run time for live threads.

system_time
Total system run time for live threads.

DESCRIPTION

The task_thread_times_info structure defines thread execution time statistics for tasks. The task_info function returns these times for a specified task. The thread_info function returns this information for a specific thread.

RELATED INFORMATION

Functions: task_info, thread_info.

Data Structures: task_basic_info, thread_basic_info. \ No newline at end of file +

task_thread_times_info

+
+

+Structure - Defines thread execution times information for tasks. +

SYNOPSIS

+
+struct task_thread_times_info
+{
+       time_value_t         user_time;
+       time_value_t       system_time;
+};
+
+typedef struct task_thread_times_info* task_thread_times_info_t;
+
+

FIELDS

+
+

+

user_time +
+Total user run time for live threads. +

+

system_time +
+Total system run time for live threads. +
+

DESCRIPTION

+

+The task_thread_times_info structure defines thread +execution time statistics +for tasks. The task_info function returns these times +for a specified task. The +thread_info function returns this information for a specific thread. +

RELATED INFORMATION

+

+Functions: +task_info, +thread_info. +

+Data Structures: +task_basic_info, +thread_basic_info. 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 @@ -

task_threads

Function - Return the target task's list of threads.

SYNOPSIS

kern_return_t   task_threads
                (task_t                                    task,
                 thread_act_port_array_t            thread_list,
                 mach_msg_type_number_t*           thread_count);

PARAMETERS

task
[in task send right] The port for the task for which the thread list is to be returned.

thread_list
[out pointer to dynamic array of thread send rights] The returned list of threads within task, in no particular order.

thread_count
[out scalar] The returned count of threads in thread_list.

DESCRIPTION

The task_threads function returns a list of the threads within task. The calling task or thread also receives a send right to the kernel port for each listed thread.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: thread_create, thread_terminate, thread_suspend. \ No newline at end of file +

task_threads

+
+

+Function - Return the target task's list of threads. +

SYNOPSIS

+
+kern_return_t   task_threads
+                (task_t                                    task,
+                 thread_act_port_array_t            thread_list,
+                 mach_msg_type_number_t*           thread_count);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] +The port for the task for which the thread list is to +be returned. +

+

thread_list +
+[out pointer to dynamic array of thread send rights] +The returned list of +threads within task, in no particular order. +

+

thread_count +
+[out scalar] +The returned count of threads in thread_list. +
+

DESCRIPTION

+

+The task_threads function returns a list of the threads +within task. The calling +task or thread also receives a send right to the kernel port +for each listed thread. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +thread_create, +thread_terminate, +thread_suspend. 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 @@ -

thread_abort

Function - Abort a thread.

SYNOPSIS

kern_return_t   thread_abort
                (thread_act_t                     target_thread);

PARAMETERS

target_thread
[in thread send right] The thread to be aborted.

DESCRIPTION

The thread_abort function aborts page faults and any message primitive calls in use by target_thread. 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.

If its state is not modified before it resumes, the thread will retry an aborted page fault. The Mach message trap returns either MACH_SEND_INTERRUPTED or MACH_RCV_INTERRUPTED, depending on whether the send or the receive side was interrupted. Note, though, that the Mach message trap is contained within the mach_msg library routine, which, by default, retries interrupted message calls.

The basic purpose of thread_abort is to let one thread cleanly stop another thread (target_thread). The target thread is stopped in such a manner that its future execution can be controlled in a predictable way. When thread_abort returns, the target thread will appear to have just returned from the kernel (if it had been in kernel mode).

NOTES

By way of comparison, the thread_suspend function keeps the target thread from executing any further instructions at the user level, including the return from a system call. The thread_get_state function returns the thread's user state, while thread_set_state allows modification of the user state.

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 thread_set_state.) As a result, when the thread resumes, the system call can return, producing a change in the user state and, possibly, user memory.

For a thread executing within a system call, thread_abort 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 thread_set_state, it will not be altered un-predictably by any unexpected system call side effects.

For example, to simulate a POSIX signal, use the following sequence of calls:

thread_suspend\(emTo stop the thread.
thread_abort\(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.
thread_set_state\(emTo modify the thread's user state to simulate a procedure call to the signal handler.
thread_resume\(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.

CAUTIONS

As a rule, do not use thread_abort 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.

thread_abort will abort any non-atomic operation (such as a multi-page memory_object_data_supply) at an arbitrary point in a non-restartable way. Such problems can be avoided by using thread_abort_safely.

RETURN VALUES

KERN_EXCEPTION_PROTECTED
The thread is processing a protected exception.

RELATED INFORMATION

Functions: mach_msg, thread_get_state, thread_info, thread_set_state, thread_suspend, thread_terminate, thread_abort_safely, thread_set_exception_ports. \ No newline at end of file +

thread_abort

+
+

+Function - Abort a thread. +

SYNOPSIS

+
+kern_return_t   thread_abort
+                (thread_act_t                     target_thread);
+
+

PARAMETERS

+
+

+

target_thread +
+[in thread send right] +The thread to be aborted. +
+

DESCRIPTION

+

+The thread_abort function aborts page faults and any +message primitive calls +in use by target_thread. 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. +

+If its state is not modified before it resumes, the thread will +retry an aborted +page fault. The Mach message trap returns either +MACH_SEND_INTERRUPTED or MACH_RCV_INTERRUPTED, depending +on whether the send or the +receive side was interrupted. Note, though, that the Mach message trap is +contained within the mach_msg library routine, which, +by default, retries +interrupted message calls. +

+The basic purpose of thread_abort is to let one thread +cleanly stop another thread (target_thread). +The target thread is stopped in such a manner that its +future execution can be controlled in a predictable way. When +thread_abort +returns, the target thread will appear to have just returned +from the kernel (if it +had been in kernel mode). +

NOTES

+

+By way of comparison, the thread_suspend function keeps +the target thread +from executing any further instructions at the user level, including +the return +from a system call. The thread_get_state function +returns the thread's user +state, while thread_set_state allows modification of the user state. +

+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 thread_set_state.) +As a result, +when the thread resumes, the system call can return, producing a change in the +user state and, possibly, user memory. +

+For a thread executing within a system call, thread_abort +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 +thread_set_state, it will not be altered un-predictably +by any unexpected +system call side effects. +

+For example, to simulate a POSIX signal, use the following sequence of calls: +

+
+thread_suspend\(emTo stop the thread. +
+thread_abort\(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. +
+thread_set_state\(emTo modify the thread's user state to simulate a +procedure call to the signal handler. +
+thread_resume\(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. +
+

CAUTIONS

+

+As a rule, do not use thread_abort 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. +

+thread_abort will abort any non-atomic operation (such as a multi-page +memory_object_data_supply) at an arbitrary point in a non-restartable +way. Such problems can be avoided by using thread_abort_safely. +

RETURN VALUES

+
+

+

KERN_EXCEPTION_PROTECTED +
+The thread is processing a protected exception. +
+

RELATED INFORMATION

+

+Functions: +mach_msg, +thread_get_state, +thread_info, +thread_set_state, +thread_suspend, +thread_terminate, +thread_abort_safely, +thread_set_exception_ports. 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 @@ -

thread_abort_safely

Function - Abort a thread, restartably.

SYNOPSIS

kern_return_t   thread_abort_safely
                (thread_act_t                     target_thread);

PARAMETERS

target_thread
[in thread send right] The thread to be aborted.

DESCRIPTION

The thread_abort_safely function aborts page faults and any message primitive calls in use by target_thread. 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.

If its state is not modified before it resumes, the thread will retry an aborted page fault. The Mach message trap returns either MACH_SEND_INTERRUPTED or MACH_RCV_INTERRUPTED, depending on whether the send or the receive side was interrupted. Note, though, that the Mach message trap is contained within the mach_msg library routine, which, by default, retries interrupted message calls.

The basic purpose of thread_abort_safely is to let one thread cleanly stop another thread (target_thread). The target thread is stopped in such a manner that its future execution can be controlled in a predictable way. When thread_abort_safely returns (if successful), the target thread will appear to have just returned from the kernel (if it had been in kernel mode).

NOTES

By way of comparison, the thread_suspend function keeps the target thread from executing any further instructions at the user level, including the return from a system call. The thread_get_state function returns the thread's user state, while thread_set_state allows modification of the user state.

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 thread_set_state.) As a result, when the thread resumes, the system call can return, producing a change in the user state and, possibly, user memory.

For a thread executing within a system call, thread_abort_safely 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 thread_set_state, it will not be altered un-predictably by any unexpected system call side effects.

For example, to simulate a POSIX signal, use the following sequence of calls:

thread_suspend\(emTo stop the thread.
thread_abort_safely\(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.
thread_set_state\(emTo modify the thread's user state to simulate a procedure call to the signal handler.
thread_resume\(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.

CAUTIONS

As a rule, do not use thread_abort_safely 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.

thread_abort_safely will not abort any non-atomic operation (such as a multi-page memory_object_data_supply 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, thread_abort would be used.

RETURN VALUES

KERN_FAILURE
The thread is in the middle of a non-restartable operation.

RELATED INFORMATION

Functions: mach_msg, thread_get_state, thread_info, thread_set_state, thread_suspend, thread_terminate, thread_abort. \ No newline at end of file +

thread_abort_safely

+
+

+Function - Abort a thread, restartably. +

SYNOPSIS

+
+kern_return_t   thread_abort_safely
+                (thread_act_t                     target_thread);
+
+

PARAMETERS

+
+

+

target_thread +
+[in thread send right] +The thread to be aborted. +
+

DESCRIPTION

+

+The thread_abort_safely function aborts page faults and any message +primitive calls in use by target_thread. 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. +

+If its state is not modified before it resumes, the thread will +retry an aborted +page fault. The Mach message trap returns either +MACH_SEND_INTERRUPTED or MACH_RCV_INTERRUPTED, depending +on whether the send or the +receive side was interrupted. Note, though, that the Mach message trap is +contained within the mach_msg library routine, which, +by default, retries +interrupted message calls. +

+The basic purpose of thread_abort_safely is to let +one thread cleanly stop +another thread (target_thread). The target thread is stopped +in such a manner that +its future execution can be controlled in a predictable way. When +thread_abort_safely returns (if successful), the target +thread will appear to have just +returned from the kernel (if it had been in kernel mode). +

NOTES

+

+By way of comparison, the thread_suspend function keeps +the target thread +from executing any further instructions at the user level, including +the return +from a system call. The thread_get_state function +returns the thread's user +state, while thread_set_state allows modification of the user state. +

+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 thread_set_state.) +As a result, +when the thread resumes, the system call can return, producing a change in the +user state and, possibly, user memory. +

+For a thread executing within a system call, thread_abort_safely +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 +thread_set_state, it will not be altered un-predictably +by any unexpected +system call side effects. +

+For example, to simulate a POSIX signal, use the following sequence of calls: +

+
+thread_suspend\(emTo stop the thread. +
+thread_abort_safely\(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. +
+thread_set_state\(emTo modify the thread's user state to simulate a +procedure call to the signal handler. +
+thread_resume\(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. +
+

CAUTIONS

+

+As a rule, do not use thread_abort_safely 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. +

+thread_abort_safely will not abort any non-atomic operation +(such as a +multi-page memory_object_data_supply 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, thread_abort would be used. +

RETURN VALUES

+
+

+

KERN_FAILURE +
+The thread is in the middle of a non-restartable operation. +
+

RELATED INFORMATION

+

+Functions: +mach_msg, +thread_get_state, +thread_info, +thread_set_state, +thread_suspend, +thread_terminate, +thread_abort. 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 @@ -

thread_activation_create

Function - Create a thread activation.

SYNOPSIS

kern_return_t   thread_activation_create
                (task_t                                    task,
                 mach_port_name_t                      RPC_port,
                 vm_offset_t                         user_stack,
                 vm_size_t                           stack_size,
                 thread_act_t                      thread_act_t);

PARAMETERS

task
[in task send right] The port for the task that is to contain the new thread activation.

RPC_port
[in receive right] A receive right held by the task, or a port set in the task.

user_stack
[in scalar] The virtual address in the task to be used as the starting ad- dress of the user-level stack.

new_act
[out thread send right] The kernel-assigned name for the new thread ac- tivation.

DESCRIPTION

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.

NOTES

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).

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create, mach_port_allocate_subsystem, \ No newline at end of file +

thread_activation_create

+
+

+Function - Create a thread activation. +

SYNOPSIS

+
+kern_return_t   thread_activation_create
+                (task_t                                    task,
+                 mach_port_name_t                      RPC_port,
+                 vm_offset_t                         user_stack,
+                 vm_size_t                           stack_size,
+                 thread_act_t                      thread_act_t);
+
+

PARAMETERS

+
+

+

task +
+[in task send right] The port for the task that is to contain the new +thread activation. +

+

RPC_port +
+[in receive right] A receive right held by the task, or a port set in the +task. +

+

user_stack +
+[in scalar] The virtual address in the task to be used as the starting ad- +dress of the user-level stack. +

+

new_act +
+[out thread send right] The kernel-assigned name for the new thread ac- +tivation. +
+

DESCRIPTION

+

+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. +

NOTES

+

+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). +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_create, +mach_port_allocate_subsystem, 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 @@ -

thread_assign

Function - Assign a thread to a processor set.

SYNOPSIS

kern_return_t   thread_assign
                (thread_act_t                            thread,
                 processor_set_t                  processor_set);

PARAMETERS

thread
[in thread send right] The thread to be assigned.

processor_set
[in processor-set-control send right] The control port for the processor set into which the thread is to be assigned.

DESCRIPTION

The thread_assign function assigns thread to the set 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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: thread_assign_default, thread_get_assignment, processor_set_create, processor_set_info, task_assign. \ No newline at end of file +

thread_assign

+
+

+Function - Assign a thread to a processor set. +

SYNOPSIS

+
+kern_return_t   thread_assign
+                (thread_act_t                            thread,
+                 processor_set_t                  processor_set);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +The thread to be assigned. +

+

processor_set +
+[in processor-set-control send right] +The control port for the processor +set into which the thread is to be assigned. +
+

DESCRIPTION

+

+The thread_assign function assigns thread to the set +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. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +thread_assign_default, +thread_get_assignment, +processor_set_create, +processor_set_info, +task_assign. 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 @@ -

thread_assign_default

Function - Assign a thread to the default processor set.

SYNOPSIS

kern_return_t   thread_assign_default
                (thread_act_t                            thread);

PARAMETERS

thread
[in thread send right] The thread to be assigned.

DESCRIPTION

The thread_assign_default function assigns thread 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.

NOTES

This variant of thread_assign exists because the control port for the default processor set is privileged, and therefore not available to most tasks.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: thread_assign, thread_get_assignment, processor_set_create, processor_set_info, task_assign. \ No newline at end of file +

thread_assign_default

+
+

+Function - Assign a thread to the default processor set. +

SYNOPSIS

+
+kern_return_t   thread_assign_default
+                (thread_act_t                            thread);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +The thread to be assigned. +
+

DESCRIPTION

+

+The thread_assign_default function assigns thread 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. +

NOTES

+

+This variant of thread_assign exists because the control +port for the default +processor set is privileged, and therefore not available to most tasks. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +thread_assign, +thread_get_assignment, +processor_set_create, +processor_set_info, +task_assign. 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 @@ -

thread_basic_info

Structure - Defines basic information for a thread.

SYNOPSIS

struct thread_basic_info
{
       time_value_t     user_time;
       time_value_t   system_time;
       integer_t        cpu_usage;
       policy_t            policy;
       integer_t        run_state;
       integer_t            flags;
       integer_t    suspend_count;
       integer_t       sleep_time;
};

typedef struct thread_basic_info* thread_basic_info_t;

FIELDS

user_time
The total user run time for the thread.

system_time
The total system run time for the thread.

cpu_usage
Scaled CPU usage percentage for the thread.

policy
Scheduling policy in effect

run_state
The thread's run state. Possible values are:

TH_STATE_RUNNING
The thread is running normally.

TH_STATE_STOPPED
The thread is stopped.

TH_STATE_WAITING
The thread is waiting normally.

TH_STATE_UNINTERRUPTIBLE
The thread is in an un-interruptible wait state.

TH_STATE_HALTED
The thread is halted at a clean point.

flags
Swap/idle flags for the thread. Possible values are:

TH_FLAGS_SWAPPED
The thread is swapped out.

TH_FLAGS_IDLE
The thread is an idle thread.

suspend_count
The current suspend count for the thread.

sleep_time
The number of seconds that the thread has been sleeping.

DESCRIPTION

The thread_basic_info structure defines the basic information array for threads. The thread_info function returns this array for a specified thread.

RELATED INFORMATION

Functions: thread_info.

Data Structures: policy_fifo_info, policy_rr_info, policy_timeshare_info. \ No newline at end of file +

thread_basic_info

+
+

+Structure - Defines basic information for a thread. +

SYNOPSIS

+
+struct thread_basic_info
+{
+       time_value_t     user_time;
+       time_value_t   system_time;
+       integer_t        cpu_usage;
+       policy_t            policy;
+       integer_t        run_state;
+       integer_t            flags;
+       integer_t    suspend_count;
+       integer_t       sleep_time;
+};
+
+typedef struct thread_basic_info* thread_basic_info_t;
+
+

FIELDS

+
+
user_time +
+The total user run time for the thread. +

+

system_time +
+The total system run time for the thread. +

+

cpu_usage +
+Scaled CPU usage percentage for the thread. +

+

policy +
+Scheduling policy in effect +

+

run_state +
+The thread's run state. Possible values are: +
+

+

TH_STATE_RUNNING +
+The thread is running normally. +

+

TH_STATE_STOPPED +
+The thread is stopped. +

+

TH_STATE_WAITING +
+The thread is waiting normally. +

+

TH_STATE_UNINTERRUPTIBLE +
+The thread is in an un-interruptible wait state. +

+

TH_STATE_HALTED +
+The thread is halted at a clean point. +
+

+

flags +
+Swap/idle flags for the thread. Possible values are: +
+

+

TH_FLAGS_SWAPPED +
+The thread is swapped out. +

+

TH_FLAGS_IDLE +
+The thread is an idle thread. +
+

+

suspend_count +
+The current suspend count for the thread. +

+

sleep_time +
+The number of seconds that the thread has been sleeping. +
+

DESCRIPTION

+

+The thread_basic_info structure defines the basic information +array for threads. +The thread_info function returns this array for a specified thread. +

RELATED INFORMATION

+

+Functions: +thread_info. +

+Data Structures: +policy_fifo_info, +policy_rr_info, +policy_timeshare_info. 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 @@ -

thread_create

Function - Create a thread within a task.

SYNOPSIS

kern_return_t   thread_create
                (task_t                             parent_task,
                 thread_act_t                      child_thread);

PARAMETERS

parent_task
[in task send right] The port for the task that is to contain the new thread.

child_thread
[out thread send right] The kernel-assigned name for the new thread.

DESCRIPTION

The thread_create function creates a new thread within parent_task. The new thread has a suspend count of one and no processor state.

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 child_thread. The new thread's exception ports are set to MACH_PORT_NULL.

NOTES

To get a new thread running, first use thread_set_state to set a processor state for the thread. Then, use thread_resume to schedule the thread for execution. Alternately, use thread_create_running.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create, task_threads, thread_get_special_port, thread_get_state, thread_resume, thread_set_special_port, thread_set_state, thread_suspend, thread_terminate, thread_create_running. \ No newline at end of file +

thread_create

+
+

+Function - Create a thread within a task. +

SYNOPSIS

+
+kern_return_t   thread_create
+                (task_t                             parent_task,
+                 thread_act_t                      child_thread);
+
+

PARAMETERS

+
+

+

parent_task +
+[in task send right] +The port for the task that is to contain the new +thread. +

+

child_thread +
+[out thread send right] +The kernel-assigned name for the new thread. +
+

DESCRIPTION

+

+The thread_create function creates a new thread within +parent_task. The new thread has a suspend count of one and +no processor state. +

+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 child_thread. +The new thread's exception ports are set to MACH_PORT_NULL. +

NOTES

+

+To get a new thread running, first use thread_set_state +to set a processor state +for the thread. Then, use thread_resume to schedule +the thread for execution. +Alternately, use thread_create_running. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_create, +task_threads, +thread_get_special_port, +thread_get_state, +thread_resume, +thread_set_special_port, +thread_set_state, +thread_suspend, +thread_terminate, +thread_create_running. 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 @@ -

thread_create_running

Function - Optimized creation of a running thread.

SYNOPSIS

kern_return_t   thread_create_running
                (task_t                             parent_task,
                 thread_state_flavor_t                   flavor,
                 thread_state_t                           state,
                 thread_act_t                      child_thread);

PARAMETERS

parent_task
[in task send right] The port for the task that is to contain the new thread.

flavor
[in scalar] The type of state to establish. Valid values correspond to supported machine architecture features.

state
[pointer to in structure] State information for the specified thread.

child_thread
[out thread send right] The kernel-assigned name for the new thread.

DESCRIPTION

The thread_create_running function creates a new thread within parent_task. The new thread has is not suspended. Its initial state is given by state. flavor specifies the type of state to set.

The format of the state to set is machine specific; it is defined in \*L\*O.

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 child_thread. The new thread's exception ports are set to MACH_PORT_NULL.

NOTES

This is an optimized form of the sequence: thread_create, thread_set_state and thread_resume.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create, task_threads, thread_get_special_port, thread_get_state, thread_resume, thread_set_special_port, thread_set_state, thread_suspend, thread_terminate, thread_create. \ No newline at end of file +

thread_create_running

+
+

+Function - Optimized creation of a running thread. +

SYNOPSIS

+
+kern_return_t   thread_create_running
+                (task_t                             parent_task,
+                 thread_state_flavor_t                   flavor,
+                 thread_state_t                           state,
+                 thread_act_t                      child_thread);
+
+

PARAMETERS

+
+

+

parent_task +
+[in task send right] +The port for the task that is to contain the new +thread. +

+

flavor +
+[in scalar] +The type of state to establish. Valid values correspond to +supported machine architecture features. +

+

state +
+[pointer to in structure] +State information for the specified thread. +

+

child_thread +
+[out thread send right] +The kernel-assigned name for the new thread. +
+

DESCRIPTION

+

+The thread_create_running function creates a new thread +within parent_task. +The new thread has is not suspended. Its initial state is given +by state. flavor specifies the type of state to set. +

+The format of the state to set is machine specific; it is defined in +\*L\*O. +

+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 child_thread. +The new thread's exception ports are set to MACH_PORT_NULL. +

NOTES

+

+This is an optimized form of the sequence: thread_create, +thread_set_state +and thread_resume. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_create, +task_threads, +thread_get_special_port, +thread_get_state, +thread_resume, +thread_set_special_port, +thread_set_state, +thread_suspend, +thread_terminate, +thread_create. 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 @@ -

thread_depress_abort

Function - Cancel thread scheduling depression.

SYNOPSIS

kern_return_t   thread_depress_abort
                (thread_act_t                            thread);

PARAMETERS

thread
[in thread send right] Thread whose scheduling depression is canceled.

DESCRIPTION

The thread_depress_abort function cancels any scheduling depression effective for thread caused by a thread_switch call.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: thread_abort, thread_switch. \ No newline at end of file +

thread_depress_abort

+
+

+Function - Cancel thread scheduling depression. +

SYNOPSIS

+
+kern_return_t   thread_depress_abort
+                (thread_act_t                            thread);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +Thread whose scheduling depression is canceled. +
+

DESCRIPTION

+

+The thread_depress_abort function cancels any scheduling depression +effective for thread caused by a thread_switch call. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +thread_abort, +thread_switch. 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 @@ -

thread_get_assignment

Function - Return the processor set to which a thread is assigned.

SYNOPSIS

kern_return_t   thread_get_assignment
                (thread_act_t                            thread,
                 processor_set_name_t             processor_set);

PARAMETERS

thread
[in thread send right] The thread whose assignment is desired.

processor_set
[out processor-set-name send right] The name port for the processor set into which the thread is assigned.

DESCRIPTION

The thread_get_assignment function returns the name port to the processor set to which thread is currently assigned. This port can only be used to obtain information about the processor set.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: thread_assign, thread_assign_default, processor_set_create, processor_set_info, task_assign. \ No newline at end of file +

thread_get_assignment

+
+

+Function - Return the processor set to which a thread is assigned. +

SYNOPSIS

+
+kern_return_t   thread_get_assignment
+                (thread_act_t                            thread,
+                 processor_set_name_t             processor_set);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +The thread whose assignment is desired. +

+

processor_set +
+[out processor-set-name send right] +The name port for the processor +set into which the thread is assigned. +
+

DESCRIPTION

+

+The thread_get_assignment function returns the name +port to the processor set to which thread is currently assigned. +This port can only be used to obtain information about the processor set. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +thread_assign, +thread_assign_default, +processor_set_create, +processor_set_info, +task_assign. 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 @@ -

thread_get_exception_ports

Function - Return a send right to an exception port.

SYNOPSIS

kern_return_t   thread_get_exception_ports
                (thread_act_t                            thread,
                 exception_mask_t               exception_types,
                 exception_mask_array_t     old_exception_masks,
                 old_exception_masks        old_exception_count,
                 exception_port_array_t     old_exception_ports,
                 exception_behavior_array_t       old_behaviors,
                 exception_flavor_array_t           old_flavors);

PARAMETERS

thread
[in thread send right] The thread for which to return the exception ports.

exception_types
[in scalar] A flag word indicating the types of exceptions for which the exception ports are desired:

EXC_MASK_BAD_ACCESS
Could not access memory.

EXC_MASK_BAD_INSTRUCTION
Instruction failed. Illegal or undefined instruction or operand.

EXC_MASK_ARITHMETIC
Arithmetic exception.

EXC_MASK_EMULATION
Emulation instruction. Emulation support instruction encountered.

EXC_MASK_SOFTWARE
Software generated exception.

EXC_MASK_BREAKPOINT
Trace, breakpoint, etc.

EXC_MASK_SYSCALL
System call requested.

EXC_MASK_MACH_SYSCALL
System call with a number in the Mach call range requested.

old_exception_masks
[out array of exception_mask_t] An array, each element being a mask specifying for which exception types the corresponding element of the other arrays apply.

old_exception_count
[pointer to in/out scalar] On input, the maximum size of the array buffers; on output, the number of returned sets returned.

old_exception_ports
[out array of exception send rights] The returned exception ports.

old_behaviors
[out array of exception_behavior_t] The type of exception message to be sent. Defined types are:

EXCEPTION_DEFAULT
Send a catch_exception_raise message including the thread identity.

EXCEPTION_STATE
Send a catch_exception_raise_state message including the thread state.

EXCEPTION_STATE_IDENTITY
Send a catch_exception_raise_state_identity message including the thread identity and state.

old_flavors
[out array of thread_state_flavor_t] The type of state to be sent with the exception message. These types are defined in \*L\*O.

DESCRIPTION

The thread_get_exception_ports function returns send rights for a specified set of exception ports belonging to thread. The call returns a set of quadruples for each unique set of in effect for the thread where the exception type mask indicates for which exception types the other values apply.

RETURN VALUES

KERN_EXCEPTION_PROTECTED
One of the requested exception ports is protected and cannot be returned.

RELATED INFORMATION

Functions: mach_thread_self, task_get_exception_ports, task_set_exception_ports, task_swap_exception_ports, thread_create, thread_set_exception_ports, thread_swap_exception_ports, catch_exception_raise. \ No newline at end of file +

thread_get_exception_ports

+
+

+Function - Return a send right to an exception port. +

SYNOPSIS

+
+kern_return_t   thread_get_exception_ports
+                (thread_act_t                            thread,
+                 exception_mask_t               exception_types,
+                 exception_mask_array_t     old_exception_masks,
+                 old_exception_masks        old_exception_count,
+                 exception_port_array_t     old_exception_ports,
+                 exception_behavior_array_t       old_behaviors,
+                 exception_flavor_array_t           old_flavors);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +The thread for which to return the exception +ports. +

+

exception_types +
+[in scalar] +A flag word indicating the types of exceptions for which the +exception ports are desired: +
+

+

EXC_MASK_BAD_ACCESS +
+Could not access memory. +

+

EXC_MASK_BAD_INSTRUCTION +
+Instruction failed. Illegal or undefined instruction or operand. +

+

EXC_MASK_ARITHMETIC +
+Arithmetic exception. +

+

EXC_MASK_EMULATION +
+Emulation instruction. Emulation support instruction +encountered. +

+

EXC_MASK_SOFTWARE +
+Software generated exception. +

+

EXC_MASK_BREAKPOINT +
+Trace, breakpoint, etc. +

+

EXC_MASK_SYSCALL +
+System call requested. +

+

EXC_MASK_MACH_SYSCALL +
+System call with a number in the Mach call range requested. +
+

+

old_exception_masks +
+[out array of exception_mask_t] +An array, each element being a mask +specifying for which exception types the corresponding element of the +other arrays apply. +

+

old_exception_count +
+[pointer to in/out scalar] +On input, the maximum size of the array +buffers; on output, the number of returned sets returned. +

+

old_exception_ports +
+[out array of exception send rights] +The returned exception ports. +

+

old_behaviors +
+[out array of exception_behavior_t] +The type of exception message to +be sent. Defined types are: +
+

+

EXCEPTION_DEFAULT +
+Send a catch_exception_raise message including the thread +identity. +

+

EXCEPTION_STATE +
+Send a catch_exception_raise_state message including the +thread state. +

+

EXCEPTION_STATE_IDENTITY +
+Send a catch_exception_raise_state_identity message +including the thread identity and state. +
+

+

old_flavors +
+[out array of thread_state_flavor_t] +The type of state to be sent with +the exception message. These types are defined in \*L\*O. +
+

DESCRIPTION

+

+The thread_get_exception_ports function returns send +rights for a specified +set of exception ports belonging to thread. The call returns +a set of quadruples + for each unique set of + in effect for the thread where +the exception +type mask indicates for which exception types the other values apply. +

RETURN VALUES

+
+

+

KERN_EXCEPTION_PROTECTED +
+One of the requested exception ports is protected and cannot be returned. +
+

RELATED INFORMATION

+

+Functions: +mach_thread_self, +task_get_exception_ports, +task_set_exception_ports, +task_swap_exception_ports, +thread_create, +thread_set_exception_ports, +thread_swap_exception_ports, +catch_exception_raise. 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 @@ -

thread_get_special_port

Function - Return a send right to the caller-specified special port.

SYNOPSIS

kern_return_t   thread_get_special_port
                (thread_act_t                            thread,
                 int                                 which_port,
                 thread                            special_port);

Macro form:

kern_return_t   thread_get_kernel_port
                (thread_act_t                            thread,
                 thread                            special_port);

PARAMETERS

thread
[in thread send right] The thread for which to return the port's send right.

which_port
[in scalar] The special port for which the send right is requested. Valid values are:

THREAD_KERNEL_PORT
[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 mach_thread_self.

special_port
[out thread-special send right] The returned value for the port.

DESCRIPTION

The thread_get_special_port function returns a send right for a special port belonging to thread.

The thread kernel port is a port for which the kernel holds the receive right. The kernel uses this port to identify the thread.

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 mach_msg function, however, any thread can pass a send right for its kernel port to another thread.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_thread_self, task_get_special_port, task_set_special_port, thread_create, thread_set_special_port. \ No newline at end of file +

thread_get_special_port

+
+

+Function - Return a send right to the caller-specified special port. +

SYNOPSIS

+
+kern_return_t   thread_get_special_port
+                (thread_act_t                            thread,
+                 int                                 which_port,
+                 thread                            special_port);
+
+ +

Macro form:

+ +
+kern_return_t   thread_get_kernel_port
+                (thread_act_t                            thread,
+                 thread                            special_port);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +The thread for which to return the port's send +right. +

+

which_port +
+[in scalar] +The special port for which the send right is requested. Valid +values are: +
+

+

THREAD_KERNEL_PORT +
+[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 mach_thread_self. +
+

+

special_port +
+[out thread-special send right] +The returned value for the port. +
+

DESCRIPTION

+

+The thread_get_special_port function returns a send +right for a special port +belonging to thread. +

+The thread kernel port is a port for which the kernel holds the +receive right. The +kernel uses this port to identify the thread. +

+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 mach_msg +function, however, any +thread can pass a send right for its kernel port to another thread. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_thread_self, +task_get_special_port, +task_set_special_port, +thread_create, +thread_set_special_port. 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 @@ -

thread_get_state

Function - Return the execution state for a thread.

SYNOPSIS

kern_return_t   thread_get_state
                (thread_act_t                     target_thread,
                 thread_state_flavor_t                   flavor,
                 thread_state_t                       old_state,
                 mach_msg_type_number_t         old_state_count);

PARAMETERS

target_thread
[in thread send right] The thread for which the execution state is to be returned. The calling thread cannot specify itself.

flavor
[in scalar] The type of execution state to be returned. Valid values correspond to supported machined architectures.

old_state
[out structure] State information for the specified thread.

old_state_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The thread_get_state function returns the execution state (for example, the machine registers) for target_thread. flavor specifies the type of state information returned.

The format of the data returned is machine specific; it is defined in \*L\*O.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_info, thread_info, thread_set_state. \ No newline at end of file +

thread_get_state

+
+

+Function - Return the execution state for a thread. +

SYNOPSIS

+
+kern_return_t   thread_get_state
+                (thread_act_t                     target_thread,
+                 thread_state_flavor_t                   flavor,
+                 thread_state_t                       old_state,
+                 mach_msg_type_number_t         old_state_count);
+
+

PARAMETERS

+
+

+

target_thread +
+[in thread send right] +The thread for which the execution state is to be +returned. The calling thread cannot specify itself. +

+

flavor +
+[in scalar] +The type of execution state to be returned. Valid values +correspond to supported machined architectures. +

+

old_state +
+[out structure] +State information for the specified thread. +

+

old_state_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The thread_get_state function returns the execution +state (for example, the +machine registers) for target_thread. flavor specifies the type +of state information +returned. +

+The format of the data returned is machine specific; it is defined in +\*L\*O. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_info, +thread_info, +thread_set_state. 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 @@ -

thread_info

Function - Return information about a thread.

SYNOPSIS

kern_return_t   thread_info
                (thread_act_t                     target_thread,
                 thread_flavor_t                         flavor,
                 thread_info_t                      thread_info,
                 mach_msg_type_number_t       thread_info_count);

PARAMETERS

target_thread
[in thread send right] The thread for which the information is to be returned.

flavor
[in scalar] The type of information to be returned. Valid values are:

THREAD_BASIC_INFO
Returns basic information about the thread, such as the thread's run state and suspend count. The returned structure is thread_basic_info.

THREAD_SCHED_FIFO_INFO
Returns FIFO scheduling policy information about the thread. The returned structure is policy_fifo_info.

THREAD_SCHED_RR_INFO
Returns round-robin scheduling policy information about the thread. The returned structure is policy_rr_info.

THREAD_SCHED_TIMESHARE_INFO
Returns timeshare scheduling policy information about the thread. The returned structure is policy_timeshare_info.

thread_info
[out structure] Information about the specified thread.

thread_info_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The thread_info function returns an information structure of type flavor.

NOTES

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 THREAD_BASIC_INFO.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_info, task_threads, thread_get_state, thread_set_special_port, thread_set_state.

Data Structures: thread_basic_info, policy_timeshare_info, policy_fifo_info, policy_rr_info. \ No newline at end of file +

thread_info

+
+

+Function - Return information about a thread. +

SYNOPSIS

+
+kern_return_t   thread_info
+                (thread_act_t                     target_thread,
+                 thread_flavor_t                         flavor,
+                 thread_info_t                      thread_info,
+                 mach_msg_type_number_t       thread_info_count);
+
+

PARAMETERS

+
+

+

target_thread +
+[in thread send right] +The thread for which the information is to be +returned. +

+

flavor +
+[in scalar] +The type of information to be returned. Valid values are: +
+

+

THREAD_BASIC_INFO +
+Returns basic information about the thread, such as the +thread's run state and suspend count. The returned structure is +thread_basic_info. +

+

THREAD_SCHED_FIFO_INFO +
+Returns FIFO scheduling policy information about the thread. +The returned structure is policy_fifo_info. +

+

THREAD_SCHED_RR_INFO +
+Returns round-robin scheduling policy information about the +thread. The returned structure is policy_rr_info. +

+

THREAD_SCHED_TIMESHARE_INFO +
+Returns timeshare scheduling policy information about the +thread. The returned structure is policy_timeshare_info. +
+

+

thread_info +
+[out structure] +Information about the specified thread. +

+

thread_info_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The thread_info function returns an information structure +of type flavor. +

NOTES

+

+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 THREAD_BASIC_INFO. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_info, +task_threads, +thread_get_state, +thread_set_special_port, +thread_set_state. +

+Data Structures: +thread_basic_info, +policy_timeshare_info, +policy_fifo_info, +policy_rr_info. 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 @@ -

thread_policy

Function - Set target thread's scheduling policy state.

SYNOPSIS

kern_return_t   thread_policy
                (thread_act_t                            thread,
                 policy_t                                policy,
                 policy_base_t                             base,
                 base                                base_count,
                 boolean_t                            set_limit);

PARAMETERS

thread
[in thread send right] The thread scheduling policy is to be set.

policy
[in scalar] Policy to be set. The values currently defined are POLICY_TIMESHARE, POLICY_RR (round robin) and POLICY_FIFO (firstin, first-out).

base
[pointer to in structure] Base scheduling policy specific data, policy_fifo_base, policy_rr_base or policy_timeshare_base.

base_count
[in scalar] The size of the buffer (in natural-sized units).

set_limit
[in scalar] True if the thread's scheduling limits should be restricted to allow no more service than specified by base.

DESCRIPTION

The thread_policy function sets the scheduling policy to be applied to thread. policy must be a scheduling policy currently "enabled" for the thread's assigned processor set.

RETURN VALUES

KERN_INVALID_POLICY
The processor set to which thread is currently assigned does not currently enable policy.

KERN_POLICY_LIMIT
The specified scheduling attributes exceeds the thread's limits.

RELATED INFORMATION

Functions: processor_set_policy_control, thread_set_policy, task_policy, task_set_policy.

Data Structures: policy_fifo_info, policy_rr_info, policy_timeshare_info. \ No newline at end of file +

thread_policy

+
+

+Function - Set target thread's scheduling policy state. +

SYNOPSIS

+
+kern_return_t   thread_policy
+                (thread_act_t                            thread,
+                 policy_t                                policy,
+                 policy_base_t                             base,
+                 base                                base_count,
+                 boolean_t                            set_limit);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +The thread scheduling policy is to be set. +

+

policy +
+[in scalar] +Policy to be set. The values currently defined are POLICY_TIMESHARE, +POLICY_RR (round robin) and POLICY_FIFO (firstin, first-out). +

+

base +
+[pointer to in structure] +Base scheduling policy specific data, +policy_fifo_base, policy_rr_base or policy_timeshare_base. +

+

base_count +
+[in scalar] +The size of the buffer (in natural-sized units). +

+

set_limit +
+[in scalar] +True if the thread's scheduling limits should be restricted to +allow no more service than specified by base. +
+

DESCRIPTION

+

+The thread_policy function sets the scheduling policy +to be applied to thread. policy must be a scheduling policy +currently "enabled" for the thread's assigned processor set. +

RETURN VALUES

+
+

+

KERN_INVALID_POLICY +
+The processor set to which thread is currently assigned does +not currently enable policy. +

+

KERN_POLICY_LIMIT +
+The specified scheduling attributes exceeds the thread's limits. +
+

RELATED INFORMATION

+

+Functions: +processor_set_policy_control, +thread_set_policy, +task_policy, +task_set_policy. +

+Data Structures: +policy_fifo_info, +policy_rr_info, +policy_timeshare_info. 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 @@ -

thread_resume

Function - Resume a thread.

SYNOPSIS

kern_return_t   thread_resume
                (thread_act_t                     target_thread);

PARAMETERS

target_thread
[in thread send right] The thread to be resumed.

DESCRIPTION

The thread_resume function decrements the suspend count for target_thread by one. The thread is resumed if its suspend count goes to zero. If the suspend count is still positive, thread_resume must be repeated until the count reaches zero.

NOTES

An attempt to lower the suspend count below zero is ignored.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_resume, task_suspend, thread_create, thread_info, thread_suspend, thread_terminate. \ No newline at end of file +

thread_resume

+
+

+Function - Resume a thread. +

SYNOPSIS

+
+kern_return_t   thread_resume
+                (thread_act_t                     target_thread);
+
+

PARAMETERS

+
+

+

target_thread +
+[in thread send right] +The thread to be resumed. +
+

DESCRIPTION

+

+The thread_resume function decrements the suspend count +for target_thread +by one. The thread is resumed if its suspend count goes to zero. +If the suspend +count is still positive, thread_resume must be repeated +until the count reaches +zero. +

NOTES

+

+An attempt to lower the suspend count below zero is ignored. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_resume, +task_suspend, +thread_create, +thread_info, +thread_suspend, +thread_terminate. 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 @@ -

thread_sample

Function - Perform periodic PC sampling for a thread.

SYNOPSIS

kern_return_t   thread_sample
                (thread_act_t                     sample_thread,
                 mach_port_make_send_t               reply_port);

PARAMETERS

sample_thread
[in thread send right] Thread whose PC is to be sampled

reply_port
[in sample receive (to be converted to send) right] Port to which PC sample buffers are sent. A value of MACH_PORT_NULL stops PC sampling for the thread.

DESCRIPTION

The thread_sample function causes the program counter (PC) of the specified sample_thread 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 reply_port in receive_samples messages.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_sample, receive_samples. \ No newline at end of file +

thread_sample

+
+

+Function - Perform periodic PC sampling for a thread. +

SYNOPSIS

+
+kern_return_t   thread_sample
+                (thread_act_t                     sample_thread,
+                 mach_port_make_send_t               reply_port);
+
+

PARAMETERS

+
+

+

sample_thread +
+[in thread send right] +Thread whose PC is to be sampled +

+

reply_port +
+[in sample receive (to be converted to send) right] +Port to which PC +sample buffers are sent. A value of MACH_PORT_NULL stops PC +sampling for the thread. +
+

DESCRIPTION

+

+The thread_sample function causes the program counter +(PC) of the specified +sample_thread 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 +reply_port in +receive_samples messages. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_sample, +receive_samples. 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 @@ -

thread_set_exception_ports

Function - Set exception ports for a thread.

SYNOPSIS

kern_return_t   thread_set_exception_ports
                (thread_act_t                            thread,
                 exception_mask_t               exception_types,
                 mach_port_t                     exception_port,
                 exception_behavior_t                  behavior,
                 thread_state_flavor_t                   flavor);

PARAMETERS

thread
[in thread send right] The thread for which to set the ports.

exception_types
[in scalar] A flag word indicating the types of exceptions for which the exception port applies:

EXC_MASK_BAD_ACCESS
Could not access memory.

EXC_MASK_BAD_INSTRUCTION
Instruction failed. Illegal or undefined instruction or operand.

EXC_MASK_ARITHMETIC
Arithmetic exception.

EXC_MASK_EMULATION
Emulation instruction. Emulation support instruction encountered.

EXC_MASK_SOFTWARE
Software generated exception.

EXC_MASK_BREAKPOINT
Trace, breakpoint, etc.

EXC_MASK_SYSCALL
System call requested.

EXC_MASK_MACH_SYSCALL
System call with a number in the Mach call range requested.

exception_port
[in exception send right] The exception port for all selected exception types.

behavior
[in scalar] The type of exception message to be sent. Defined types are:

EXCEPTION_DEFAULT
Send a catch_exception_raise message including the thread identity.

EXCEPTION_DEFAULT_PROTECTED
Send a catch_exception_raise message including the thread identity. Mark the exception port (and associated exceptions) as protected.

EXCEPTION_STATE
Send a catch_exception_raise_state message including the thread state.

EXCEPTION_STATE_PROTECTED
Send a catch_exception_raise_state message including the thread state. Mark the exception port (and associated exceptions) as protected.

EXCEPTION_STATE_IDENTITY
Send a catch_exception_raise_state_identity message including the thread identity and state.

EXCEPTION_STATE_IDENTITY_PROTECTED
Send a catch_exception_raise_state_identity message including the thread identity and state. Mark the exception port (and associated exceptions) as protected.

flavor
[in scalar] The type of state to be sent with the exception message. These types are defined in \*L\*O.

DESCRIPTION

The thread_set_exception_ports function sets a specified set of exception ports belonging to thread.

NOTES

If the value of the EXC_MACH_SYSCALL 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.

A "protected" exception port is one which cannot be fetched and for which exception processing cannot be aborted (thread_abort).

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_thread_self, task_get_exception_ports, task_set_exception_ports, task_swap_exception_ports, thread_create, thread_get_exception_ports, thread_swap_exception_ports, catch_exception_raise, thread_abort. \ No newline at end of file +

thread_set_exception_ports

+
+

+Function - Set exception ports for a thread. +

SYNOPSIS

+
+kern_return_t   thread_set_exception_ports
+                (thread_act_t                            thread,
+                 exception_mask_t               exception_types,
+                 mach_port_t                     exception_port,
+                 exception_behavior_t                  behavior,
+                 thread_state_flavor_t                   flavor);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +The thread for which to set the ports. +

+

exception_types +
+[in scalar] +A flag word indicating the types of exceptions for which the +exception port applies: +
+

+

EXC_MASK_BAD_ACCESS +
+Could not access memory. +

+

EXC_MASK_BAD_INSTRUCTION +
+Instruction failed. Illegal or undefined instruction or operand. +

+

EXC_MASK_ARITHMETIC +
+Arithmetic exception. +

+

EXC_MASK_EMULATION +
+Emulation instruction. Emulation support instruction +encountered. +

+

EXC_MASK_SOFTWARE +
+Software generated exception. +

+

EXC_MASK_BREAKPOINT +
+Trace, breakpoint, etc. +

+

EXC_MASK_SYSCALL +
+System call requested. +

+

EXC_MASK_MACH_SYSCALL +
+System call with a number in the Mach call range requested. +
+

+

exception_port +
+[in exception send right] +The exception port for all selected exception +types. +

+

behavior +
+[in scalar] +The type of exception message to be sent. Defined types are: +
+

+

EXCEPTION_DEFAULT +
+Send a catch_exception_raise message including the thread +identity. +

+

EXCEPTION_DEFAULT_PROTECTED +
+Send a catch_exception_raise message including the thread +identity. Mark the exception port (and associated exceptions) +as protected. +

+

EXCEPTION_STATE +
+Send a catch_exception_raise_state message including the +thread state. +

+

EXCEPTION_STATE_PROTECTED +
+Send a catch_exception_raise_state message including the +thread state. Mark the exception port (and associated +exceptions) as protected. +

+

EXCEPTION_STATE_IDENTITY +
+Send a catch_exception_raise_state_identity message +including the thread identity and state. +

+

EXCEPTION_STATE_IDENTITY_PROTECTED +
+Send a catch_exception_raise_state_identity message +including the thread identity and state. Mark the exception port +(and associated exceptions) as protected. +
+

+

flavor +
+[in scalar] +The type of state to be sent with the exception message. +These types are defined in \*L\*O. +
+

DESCRIPTION

+

+The thread_set_exception_ports function sets a specified +set of exception +ports belonging to thread. +

NOTES

+

+If the value of the EXC_MACH_SYSCALL 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. +

+A "protected" exception port is one which cannot be fetched and for which +exception processing cannot be aborted (thread_abort). +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_thread_self, +task_get_exception_ports, +task_set_exception_ports, +task_swap_exception_ports, +thread_create, +thread_get_exception_ports, +thread_swap_exception_ports, +catch_exception_raise, +thread_abort. 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 @@ -

thread_set_policy

Function - Set target thread's scheduling policy state. (Protected Interface.)

SYNOPSIS

kern_return_t   thread_set_policy
                (thread_act_t                            thread,
                 processor_set_t                  processor_set,
                 policy_t                                policy,
                 policy_base_t                             base,
                 mach_msg_type_number_t              base_count,
                 policy_limit_t                           limit,
                 mach_msg_type_number_              limit_count);

PARAMETERS

thread
[in thread send right] The thread scheduling policy is to be set.

processor_set
[in processor-set-control send right] The control port for the processor set to which the thread is currently assigned.

policy
[in scalar] Policy to be set. The values currently defined are POLICY_TIMESHARE, POLICY_RR (round robin) and POLICY_FIFO (firstin, first-out).

base
[pointer to in structure] Base policy specific data, policy_fifo_base, policy_rr_base or policy_timeshare_base.

base_count
[in scalar] The size of the buffer (in natural-sized units).

limit
[pointer to in structure] Policy specific limits, policy_fifo_limit, policy_rr_limit or policy_timeshare_limit.

limit_count
[in scalar] The size of the buffer (in natural-sized units).

DESCRIPTION

The thread_set_policy function sets the scheduling attributes, both base and limit, for thread. policy may be any policy implemented by the processor set whether or not it is enabled.

RETURN VALUES

KERN_INVALID_PROCESSOR_SET
processor_set is not the thread's processor set control port.

RELATED INFORMATION

Functions: processor_set_policy_control, thread_policy, task_policy, task_set_policy.

Data Structures: policy_fifo_info, policy_rr_info, policy_timeshare_info. \ No newline at end of file +

thread_set_policy

+
+

+Function - Set target thread's scheduling policy state. (Protected Interface.) +

SYNOPSIS

+
+kern_return_t   thread_set_policy
+                (thread_act_t                            thread,
+                 processor_set_t                  processor_set,
+                 policy_t                                policy,
+                 policy_base_t                             base,
+                 mach_msg_type_number_t              base_count,
+                 policy_limit_t                           limit,
+                 mach_msg_type_number_              limit_count);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +The thread scheduling policy is to be set. +

+

processor_set +
+[in processor-set-control send right] +The control port for the processor +set to which the thread is currently assigned. +

+

policy +
+[in scalar] +Policy to be set. The values currently defined are POLICY_TIMESHARE, +POLICY_RR (round robin) and POLICY_FIFO (firstin, first-out). +

+

base +
+[pointer to in structure] +Base policy specific data, policy_fifo_base, +policy_rr_base or policy_timeshare_base. +

+

base_count +
+[in scalar] +The size of the buffer (in natural-sized units). +

+

limit +
+[pointer to in structure] +Policy specific limits, policy_fifo_limit, +policy_rr_limit or policy_timeshare_limit. +

+

limit_count +
+[in scalar] +The size of the buffer (in natural-sized units). +
+

DESCRIPTION

+

+The thread_set_policy function sets the scheduling +attributes, both base and limit, for thread. +policy may be any policy implemented by the processor set +whether or not it is enabled. +

RETURN VALUES

+
+

+

KERN_INVALID_PROCESSOR_SET +
+processor_set is not the thread's processor set control port. +
+

RELATED INFORMATION

+

+Functions: +processor_set_policy_control, +thread_policy, +task_policy, +task_set_policy. +

+Data Structures: +policy_fifo_info, +policy_rr_info, +policy_timeshare_info. 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 @@ -

thread_set_special_port

Function - Set caller-specified special port belonging to the target thread.

SYNOPSIS

kern_return_t   thread_set_special_port
                (thread_act_t                            thread,
                 int                                 which_port,
                 mach_port_t                       special_port);

Macro form:

kern_return_t   thread_set_kernel_port
                (thread_act_t                            thread,
                 mach_port_t                       special_port);

PARAMETERS

thread
[in thread send right] The thread for which to set the port.

which_port
[in scalar] The special port to be set. Valid values are:

THREAD_KERNEL_PORT
[thread-self port] The thread's kernel port. Used by the kernel to receive messages from the thread. This is the port returned by mach_thread_self.

special_port
[in thread-special send right] The value for the port.

DESCRIPTION

The thread_set_special_port function sets a special port belonging to thread.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_thread_self, task_get_special_port, task_set_special_port, thread_create, thread_get_special_port. \ No newline at end of file +

thread_set_special_port

+
+

+Function - Set caller-specified special port belonging to the target thread. +

SYNOPSIS

+
+kern_return_t   thread_set_special_port
+                (thread_act_t                            thread,
+                 int                                 which_port,
+                 mach_port_t                       special_port);
+
+ +

Macro form:

+
+kern_return_t   thread_set_kernel_port
+                (thread_act_t                            thread,
+                 mach_port_t                       special_port);
+
+

PARAMETERS

+
+

+

thread +
+[in thread send right] +The thread for which to set the port. +

+

which_port +
+[in scalar] +The special port to be set. Valid values are: +
+

+

THREAD_KERNEL_PORT +
+[thread-self port] The thread's kernel port. Used by the kernel +to receive messages from the thread. This is the port returned +by mach_thread_self. +
+

+

special_port +
+[in thread-special send right] +The value for the port. +
+

DESCRIPTION

+

+The thread_set_special_port function sets a special +port belonging to thread. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +mach_thread_self, +task_get_special_port, +task_set_special_port, +thread_create, +thread_get_special_port. 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 @@ -

thread_set_state

Function - Set the target thread's user-mode execution state.

SYNOPSIS

kern_return_t   thread_set_state
                (thread_act_t                     target_thread,
                 thread_state_flavor_t                   flavor,
                 thread_state_t                       new_state,
                 target_thread                  new_state_count);

PARAMETERS

target_thread
[in thread send right] The thread for which to set the execution state. The calling thread cannot specify itself.

flavor
[in scalar] The type of state to set. Valid values correspond to supported machine architecture features.

new_state
[pointer to in structure] State information for the specified thread.

new_state_count
[in scalar] The size of the buffer (in natural-sized units).

DESCRIPTION

The thread_set_state function sets the execution state (for example, the machine registers) for target_thread. flavor specifies the type of state to set.

The format of the state to set is machine specific; it is defined in mach/thread_status.h.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_info, thread_get_state, thread_info. \ No newline at end of file +

thread_set_state

+
+

+Function - Set the target thread's user-mode execution state. +

SYNOPSIS

+
+kern_return_t   thread_set_state
+                (thread_act_t                     target_thread,
+                 thread_state_flavor_t                   flavor,
+                 thread_state_t                       new_state,
+                 target_thread                  new_state_count);
+
+

PARAMETERS

+
+

+

target_thread +
+[in thread send right] +The thread for which to set the execution state. +The calling thread cannot specify itself. +

+

flavor +
+[in scalar] +The type of state to set. Valid values correspond to +supported machine architecture features. +

+

new_state +
+[pointer to in structure] +State information for the specified thread. +

+

new_state_count +
+[in scalar] +The size of the buffer (in natural-sized units). +
+

DESCRIPTION

+

+The thread_set_state function sets the execution state +(for example, the +machine registers) for target_thread. flavor specifies the type +of state to set. +

+The format of the state to set is machine specific; it is defined in +mach/thread_status.h. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_info, +thread_get_state, +thread_info. 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 @@ -

thread_suspend

Function - Suspend a thread.

SYNOPSIS

kern_return_t   thread_suspend
                (thread_act_t                     target_thread);

PARAMETERS

target_thread
[in thread send right] The thread to be suspended.

DESCRIPTION

The thread_suspend function increments the suspend count for target_thread and prevents the thread from executing any more user-level instructions.

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.

To resume a suspended thread, use thread_resume. If the suspend count is greater than one, thread_resume must be repeated that number of times.

CAUTIONS

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 thread_abort function allows a system call to be aborted only if it is progressing in a predictable way.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_resume, task_suspend, thread_abort, thread_get_state, thread_info, thread_resume, thread_set_state, thread_terminate. \ No newline at end of file +

thread_suspend

+
+

+Function - Suspend a thread. +

SYNOPSIS

+
+kern_return_t   thread_suspend
+                (thread_act_t                     target_thread);
+
+

PARAMETERS

+
+

+

target_thread +
+[in thread send right] +The thread to be suspended. +
+

DESCRIPTION

+

+The thread_suspend function increments the suspend +count for target_thread +and prevents the thread from executing any more user-level instructions. +

+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. +

+To resume a suspended thread, use thread_resume. If +the suspend count is +greater than one, thread_resume must be repeated that +number of times. +

CAUTIONS

+

+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 +thread_abort function allows a system call to be aborted +only if it is progressing in a +predictable way. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_resume, +task_suspend, +thread_abort, +thread_get_state, +thread_info, +thread_resume, +thread_set_state, +thread_terminate. 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 @@ -

thread_switch

Function - Cause context switch with options.

SYNOPSIS

kern_return_t   thread_switch
                (mach_port_t                         new_thread,
                 int                                     option,
                 mach_msg_timeout_t                        time);

PARAMETERS

new_thread
[in thread send right] Thread to which the processor should switch context.

option
[in scalar] Options applicable to the context switch.

time
[in scalar] Time duration during which the thread should be affected by option.

DESCRIPTION

The thread_switch function provides low-level access to the scheduler's context switching code. new_thread 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.

The option argument specifies the interpretation and use of time. The possible values (from \*L\*O) are:

SWITCH_OPTION_NONE
The time argument is ignored.
SWITCH_OPTION_WAIT
The thread is blocked for the specified time. This wait cannot be canceled by thread_resume; only thread_abort can terminate this wait.
SWITCH_OPTION_DEPRESS
The thread's scheduling attributes are temporarily set so as to provide it with the lowest possible service for duration time. The scheduling depression is aborted when time 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 thread_abort or thread_depress_abort is applied to the current thread. Changing the thread's scheduling attributes (via thread_policy) will not affect this depression.
SWITCH_OPTION_IDLE
This option is similar to SWITCH_OPTION_DEPRESS 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 time. The scheduling depression is aborted when time 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 thread_abort or thread_depress_abort is applied to the current thread. Changing the thread's scheduling attributes (via thread_policy) will not affect this depression.

The minimum time and units of time can be obtained as the min_timeout value from the HOST_SCHED_INFO flavor of host_info.

NOTES

thread_switch 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 new_thread 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 SWITCH_OPTION_WAIT 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.

CAUTIONS

Users should beware of calling thread_switch with an invalid hint (e.g., THREAD_NULL) 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 SWITCH_OPTION_DEPRESS option in this situation is highly recommended.

thread_switch ignores policies. Users relying on the preemption semantics of a fixed time policy should be aware that thread_switch ignores these semantics; it will run the specified new_thread independent of its scheduling attributes and those of any threads that could run instead.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: thread_abort, thread_depress_abort. \ No newline at end of file +

thread_switch

+
+

+Function - Cause context switch with options. +

SYNOPSIS

+
+kern_return_t   thread_switch
+                (mach_port_t                         new_thread,
+                 int                                     option,
+                 mach_msg_timeout_t                        time);
+
+

PARAMETERS

+
+

+

new_thread +
+[in thread send right] +Thread to which the processor should switch +context. +

+

option +
+[in scalar] +Options applicable to the context switch. +

+

time +
+[in scalar] +Time duration during which the thread should be affected by +option. +
+

DESCRIPTION

+

+The thread_switch function provides low-level access +to the scheduler's +context switching code. new_thread 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. +

+The option argument specifies the interpretation and use of time. +The possible values (from \*L\*O) are: +

+
SWITCH_OPTION_NONE +
+The time argument is ignored. +
SWITCH_OPTION_WAIT +
+The thread is blocked for the specified time. This wait cannot be +canceled by thread_resume; +only thread_abort can terminate this wait. +
SWITCH_OPTION_DEPRESS +
+The thread's scheduling attributes are temporarily set so as to provide +it with the lowest possible service for duration time. The scheduling +depression is aborted when time 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 thread_abort or +thread_depress_abort is applied to the current thread. +Changing the thread's scheduling attributes (via thread_policy) +will not affect this depression. +
SWITCH_OPTION_IDLE +
+This option is similar to SWITCH_OPTION_DEPRESS 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 time. The scheduling depression is aborted +when time 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 thread_abort or +thread_depress_abort is applied to the current thread. +Changing the thread's scheduling attributes (via thread_policy) +will not affect this depression. +
+

+The minimum time and units of time can be obtained as the min_timeout +value from the HOST_SCHED_INFO flavor of host_info. +

NOTES

+

+thread_switch 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 new_thread +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 SWITCH_OPTION_WAIT +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. +

CAUTIONS

+

+Users should beware of calling thread_switch with an +invalid hint (e.g., THREAD_NULL) 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 +SWITCH_OPTION_DEPRESS option in this situation is highly recommended. +

+thread_switch ignores policies. Users relying on the +preemption semantics of a +fixed time policy should be aware that thread_switch +ignores these semantics; +it will run the specified new_thread independent of its scheduling +attributes and +those of any threads that could run instead. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +thread_abort, +thread_depress_abort. 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 @@ -

thread_terminate

Function - Destroy a thread.

SYNOPSIS

kern_return_t   thread_terminate
                (thread_act_t                     target_thread);

PARAMETERS

target_thread
[in thread send right] The thread to be destroyed.

DESCRIPTION

The thread_terminate function kills target_thread.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_terminate, task_threads, thread_create, thread_resume, thread_suspend. \ No newline at end of file +

thread_terminate

+
+

+Function - Destroy a thread. +

SYNOPSIS

+
+kern_return_t   thread_terminate
+                (thread_act_t                     target_thread);
+
+

PARAMETERS

+
+

+

target_thread +
+[in thread send right] +The thread to be destroyed. +
+

DESCRIPTION

+

+The thread_terminate function kills target_thread. +

RETURN VALUES

+

+Only generic errors apply. +

RELATED INFORMATION

+

+Functions: +task_terminate, +task_threads, +thread_create, +thread_resume, +thread_suspend. 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 @@ -

thread_wire

Function - Mark the thread as privileged with respect to kernel resources.

SYNOPSIS

kern_return_t   thread_wire
                (host_priv_t                          host_priv,
                 thread_act_t                            thread,
                 boolean_t                                wired);

PARAMETERS

host_priv
[in host-control send right] The privileged control port for the host on which the thread executes.

thread
[in thread send right] The thread to be wired.

wired
[in scalar] TRUE if the thread is to be wired.

DESCRIPTION

The thread_wire 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.

RETURN VALUES

KERN_INVALID_ARGUMENT
thread is not a thread port. .P host_priv is not the control port for the host on which thread executes.

RELATED INFORMATION

Functions: vm_wire. \ No newline at end of file +

thread_wire

+
+

+Function - Mark the thread as privileged with respect to kernel resources. +

SYNOPSIS

+
+kern_return_t   thread_wire
+                (host_priv_t                          host_priv,
+                 thread_act_t                            thread,
+                 boolean_t                                wired);
+
+

PARAMETERS

+
+

+

host_priv +
+[in host-control send right] +The privileged control port for the host on +which the thread executes. +

+

thread +
+[in thread send right] +The thread to be wired. +

+

wired +
+[in scalar] +TRUE if the thread is to be wired. +
+

DESCRIPTION

+

+The thread_wire 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. +

RETURN VALUES

+
+

+

KERN_INVALID_ARGUMENT +
+thread is not a thread port. +.P +host_priv is not the control port for the host on which thread +executes. +
+

RELATED INFORMATION

+

+Functions: +vm_wire. 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 @@ -

tvalspec

Structure - Defines format of system time values.

SYNOPSIS

struct tvalspec
{
       unsigned int       tv_sec;
       clock_res_t       tv_nsec;
};

typedef struct tvalspec tvalspec_t;

FIELDS

tv_sec
Seconds.

tv_nsec
Nanoseconds.

DESCRIPTION

The tvalspec structure defines the format of the time structure supplied to or returned from the kernel. This definition conforms to the Posix 1003.4 timespec definition where the tv_nsec structure member is valid if (0 =< tv_nsec < 109) and the time period described is ((tv_sec * 109) + tv_nsec) nanoseconds.

RELATED INFORMATION

Functions: clock_get_time, clock_set_time, clock_sleep, clock_alarm, clock_alarm_reply.

Data Structures: mapped_tvalspec. \ No newline at end of file +

tvalspec

+
+

+Structure - Defines format of system time values. +

SYNOPSIS

+
+struct tvalspec
+{
+       unsigned int       tv_sec;
+       clock_res_t       tv_nsec;
+};
+
+typedef struct tvalspec tvalspec_t;
+
+

FIELDS

+
+
tv_sec +
+Seconds. +

+

tv_nsec +
+Nanoseconds. +
+

DESCRIPTION

+

+The tvalspec structure defines the format of the time +structure supplied to or +returned from the kernel. This definition conforms to the Posix +1003.4 timespec +definition where the tv_nsec structure member is valid +if (0 =< tv_nsec < 109) and +the time period described is ((tv_sec * 109) + tv_nsec) nanoseconds. +

RELATED INFORMATION

+

+Functions: +clock_get_time, +clock_set_time, +clock_sleep, +clock_alarm, +clock_alarm_reply. +

+Data Structures: +mapped_tvalspec. 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 @@ -

vm_allocate

Function - Allocate a region of virtual memory.

SYNOPSIS

kern_return_t   vm_allocate
                (vm_task_t                          target_task,
                 vm_address_t                           address,
                 vm_size_t                                 size,
                 boolean_t                             anywhere);

PARAMETERS

target_task
[in task send right] The port for the task in whose address space the region is to be allocated.

address
[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.

size
[in scalar] The number of bytes to allocate.

anywhere
[in scalar] Placement indicator. The valid values are:

TRUE
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 address.

FALSE
The kernel allocates the region starting at address unless that space is already allocated.

DESCRIPTION

The vm_allocate function allocates a region of virtual memory in the specified task's address space. A new region is always zero filled.

If anywhere is TRUE, the returned address will be at a page boundary; otherwise, the region starts at the beginning of the virtual page containing address. size 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 size. Use host_page_size to find the current virtual page size.

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.

NOTES

To establish different protections or inheritance for the new region, use the vm_protect and vm_inherit functions.

A task's address space can contain both explicitly allocated memory and automatically allocated memory. The vm_allocate function explicitly allocates memory. The kernel automatically allocates memory to hold out-of-line data passed in a message (and received with mach_msg). The kernel allocates memory for the passed data as an integral number of pages.

This interface is machine word length dependent because of the virtual address parameter.

RETURN VALUES

KERN_INVALID_ADDRESS
The specified address is illegal or reserved.

KERN_NO_SPACE
There is not enough space in the task's address space to allocate the new region.

RELATED INFORMATION

Functions: vm_deallocate, vm_inherit, vm_protect, vm_region, host_page_size. \ No newline at end of file +

vm_allocate

+
+

+Function - Allocate a region of virtual memory. +

SYNOPSIS

+
+kern_return_t   vm_allocate
+                (vm_task_t                          target_task,
+                 vm_address_t                           address,
+                 vm_size_t                                 size,
+                 boolean_t                             anywhere);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task in whose address space the +region is to be allocated. +

+

address +
+[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. +

+

size +
+[in scalar] +The number of bytes to allocate. +

+

anywhere +
+[in scalar] +Placement indicator. The valid values are: +
+

+

TRUE +
+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 address. +

+

FALSE +
+The kernel allocates the region starting at address unless that +space is already allocated. +
+
+

DESCRIPTION

+

+The vm_allocate function allocates a region of virtual +memory in the specified +task's address space. A new region is always zero filled. +

+If anywhere is TRUE, the returned +address will be at +a page boundary; otherwise, the region starts at the beginning +of the virtual page +containing address. +size 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 size. Use host_page_size to find +the current virtual page size. +

+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. +

NOTES

+

+To establish different protections or inheritance for the new region, use the +vm_protect and vm_inherit functions. +

+A task's address space can contain both explicitly allocated memory and +automatically allocated memory. The vm_allocate function +explicitly allocates +memory. The kernel automatically allocates memory to hold out-of-line data +passed in a message (and received with mach_msg). The kernel allocates +memory for the passed data as an integral number of pages. +

+This interface is machine word length dependent because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_ADDRESS +
+The specified address is illegal or reserved. +

+

KERN_NO_SPACE +
+There is not enough space in the task's address space to allocate the +new region. +
+

RELATED INFORMATION

+

+Functions: +vm_deallocate, +vm_inherit, +vm_protect, +vm_region, +host_page_size. + 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 @@ -

vm_behavior_set

Function - Specify expected access patterns for the target VM region.

SYNOPSIS

kern_return_t   vm_behavior_set
                (vm_task_t                          target_task,
                 vm_address_t                           address,
                 vm_size_t                                 size,
                 vm_behavior_t                         behavior);

PARAMETERS

target_task
[in task send right] The port for the task in whose address space the memory object behavior is to be set.

address
[in scalar] The starting address for the memory region.

size
[in scalar] The number of bytes in the region.

behavior
[in scalar] The expected reference pattern for the memory. Possible values are:

VM_BEHAVIOR_DEFAULT
The system's default behavior. Assumes strong locality of reference, so LRU page replacement, possibly with pre-fetch, would be appropriate.

VM_BEHAVIOR_RANDOM
No particular order expected. Assumes weak locality of reference, so LRU page replacement may be ineffective.

VM_BEHAVIOR_SEQUENTIAL
Forward sequential order.

VM_BEHAVIOR_RSEQNTL
Reverse sequential order.

DESCRIPTION

The vm_behavior_set 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.

The region starts at the beginning of the virtual page containing address; it ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than size. Use host_page_size to find the current virtual page size.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_INVALID_ADDRESS
The specified address is illegal or reserved.

RELATED INFORMATION

Functions: vm_region, host_page_size. \ No newline at end of file +

vm_behavior_set

+
+

+Function - Specify expected access patterns for the target VM region. +

SYNOPSIS

+
+kern_return_t   vm_behavior_set
+                (vm_task_t                          target_task,
+                 vm_address_t                           address,
+                 vm_size_t                                 size,
+                 vm_behavior_t                         behavior);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task in whose address space the +memory object behavior is to be set. +

+

address +
+[in scalar] +The starting address for the memory region. +

+

size +
+[in scalar] +The number of bytes in the region. +

+

behavior +
+[in scalar] +The expected reference pattern for the memory. Possible +values are: +
+

+

VM_BEHAVIOR_DEFAULT +
+The system's default behavior. Assumes strong locality of +reference, so LRU page replacement, possibly with pre-fetch, +would be appropriate. +

+

VM_BEHAVIOR_RANDOM +
+No particular order expected. Assumes weak locality of +reference, so LRU page replacement may be ineffective. +

+

VM_BEHAVIOR_SEQUENTIAL +
+Forward sequential order. +

+

VM_BEHAVIOR_RSEQNTL +
+Reverse sequential order. +
+
+

DESCRIPTION

+

+The vm_behavior_set 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. +

+The region starts at the beginning of the virtual page containing +address; it ends at the end of the virtual page containing +address + size - 1. Because of this +rounding to virtual page boundaries, the amount of memory affected may be +greater than size. Use host_page_size +to find the current virtual page size. +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_ADDRESS +
+The specified address is illegal or reserved. +
+

RELATED INFORMATION

+

+Functions: +vm_region, +host_page_size. 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 @@ -

vm_copy

Function - Copy a region of virtual memory.

SYNOPSIS

kern_return_t   vm_copy
                (vm_task_t            target_task,
                 vm_address_t      source_address,
                 vm_size_t                  count,
                 vm_address_t        dest_address);

PARAMETERS

target_task
[in task send right] The port for the task whose memory is to be copied.

source_address
[in scalar] The starting address for the source region. The address must be on a page boundary.

count
[in scalar] The number of bytes in the source region. The number of bytes must convert to an integral number of virtual pages.

dest_address
[in scalar] The starting address for the destination region. The address must be on a page boundary.

DESCRIPTION

The vm_copy function copies a source region to a destination region within the same task's virtual memory. It is semantically equivalent to vm_read followed by vm_write. The destination region can overlap the source region.

The destination region must already be allocated. The source region must be readable, and the destination region must be writable.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_PROTECTION_FAILURE
The source region is protected against reading, or the destination region is protected against writing.

KERN_INVALID_ADDRESS
An address is illegal or specifies a non-allocated region, or there is not enough memory following one of the addresses.

RELATED INFORMATION

Functions: vm_protect, vm_read, vm_write, host_page_size. \ No newline at end of file +

vm_copy

+
+

+Function - Copy a region of virtual memory. +

SYNOPSIS

+
+kern_return_t   vm_copy
+                (vm_task_t            target_task,
+                 vm_address_t      source_address,
+                 vm_size_t                  count,
+                 vm_address_t        dest_address);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task whose memory is to be copied. +

+

source_address +
+[in scalar] +The starting address for the source region. The address must +be on a page boundary. +

+

count +
+[in scalar] +The number of bytes in the source region. The number of +bytes must convert to an integral number of virtual pages. +

+

dest_address +
+[in scalar] +The starting address for the destination region. The address +must be on a page boundary. +
+

DESCRIPTION

+

+The vm_copy function copies a source region to a destination +region within the +same task's virtual memory. It is semantically equivalent to +vm_read followed +by vm_write. The destination region can overlap the source region. +

+The destination region must already be allocated. The source region must be +readable, and the destination region must be writable. +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_PROTECTION_FAILURE +
+The source region is protected against reading, or the destination +region is protected against writing. +

+

KERN_INVALID_ADDRESS +
+An address is illegal or specifies a non-allocated region, or there is not +enough memory following one of the addresses. +
+

RELATED INFORMATION

+

+Functions: +vm_protect, +vm_read, +vm_write, +host_page_size. 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 @@ -

vm_deallocate

Function - Deallocate a region of virtual memory.

SYNOPSIS

kern_return_t   vm_deallocate
                (vm_task_t                          target_task,
                 vm_address_t                           address,
                 vm_size_t                                 size);

PARAMETERS

target_task
[in task send right] The port for the task in whose address space the region is to be deallocated.

address
[in scalar] The starting address for the region.

size
[in scalar] The number of bytes to deallocate.

DESCRIPTION

The vm_deallocate 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 address and ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory deallocated may be greater than size. Use host_page_size to find the current virtual page size.

vm_deallocate affects only target_task. Other tasks that have access to the deallocated memory can continue to reference it.

NOTES

vm_deallocate can be used to deallocate memory passed as out-of-line data in a message.

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_INVALID_ADDRESS
The address is illegal or specifies a non-allocated region.

RELATED INFORMATION

Functions: mach_msg, vm_allocate, vm_map, host_page_size. \ No newline at end of file +

vm_deallocate

+
+

+Function - Deallocate a region of virtual memory. +

SYNOPSIS

+
+kern_return_t   vm_deallocate
+                (vm_task_t                          target_task,
+                 vm_address_t                           address,
+                 vm_size_t                                 size);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task in whose address space the +region is to be deallocated. +

+

address +
+[in scalar] +The starting address for the region. +

+

size +
+[in scalar] +The number of bytes to deallocate. +
+

DESCRIPTION

+

+The vm_deallocate 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 +address and ends +at the end of the virtual page containing address ++ size - 1. Because of this +rounding to virtual page boundaries, the amount of memory deallocated may be +greater than size. Use host_page_size +to find the current virtual page size. +

+vm_deallocate affects only target_task. Other tasks +that have access to the deallocated memory can continue to reference it. +

NOTES

+

+vm_deallocate can be used to deallocate memory passed +as out-of-line data in a +message. +

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_ADDRESS +
+The address is illegal or specifies a non-allocated region. +
+

RELATED INFORMATION

+

+Functions: +mach_msg, +vm_allocate, +vm_map, +host_page_size. 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 @@ -

vm_inherit

Function - Set a VM region's inheritance attribute.

SYNOPSIS

kern_return_t   vm_inherit
                 (vm_task_t                   target_task,
                  vm_address_t                    address,
                  vm_size_t                          size,
                  vm_inherit_t            new_inheritance);

PARAMETERS

target_task
[in task send right] The port for the task whose address space contains the region.

address
[in scalar] The starting address for the region.

size
[in scalar] The number of bytes in the region.

new_inheritance
[in scalar] The new inheritance attribute for the region. Valid values are:

VM_INHERIT_SHARE
Allows child tasks to share the region.

VM_INHERIT_COPY
Gives child tasks a copy of the region.

VM_INHERIT_NONE
Provides no access to the region for child tasks.

DESCRIPTION

The vm_inherit 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.

Because inheritance applies to virtual pages, the specified address and size are rounded to page boundaries, as follows: the region starts at the beginning of the virtual page containing address; it ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than size. Use host_page_size to find the current virtual page size.

A parent and a child task can share the same physical memory only if the inheritance for the memory is set to VM_INHERIT_SHARE before the child task is created. Other than through the use of an external memory manager (see vm_map), this is the only way that two tasks can share memory.

Note that all the threads within a task share the task's memory.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_INVALID_ADDRESS
The address is illegal or specifies a non-allocated region.

RELATED INFORMATION

Functions: task_create, vm_map, vm_region, norma_task_create. \ No newline at end of file +

vm_inherit

+
+

+Function - Set a VM region's inheritance attribute. +

+

SYNOPSIS

+
+kern_return_t   vm_inherit
+                 (vm_task_t                   target_task,
+                  vm_address_t                    address,
+                  vm_size_t                          size,
+                  vm_inherit_t            new_inheritance);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task whose address space contains +the region. +

+

address +
+[in scalar] +The starting address for the region. +

+

size +
+[in scalar] +The number of bytes in the region. +

+

new_inheritance +
+[in scalar] +The new inheritance attribute for the region. Valid values are: +
+

+

VM_INHERIT_SHARE +
+Allows child tasks to share the region. +

+

VM_INHERIT_COPY +
+Gives child tasks a copy of the region. +

+

VM_INHERIT_NONE +
+Provides no access to the region for child tasks. +
+
+

DESCRIPTION

+

+The vm_inherit 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. +

+Because inheritance applies to virtual pages, the specified address +and size are +rounded to page boundaries, as follows: the region starts at +the beginning of the +virtual page containing address; it ends at the end of the virtual +page containing +address + size - 1. +Because of this rounding to virtual page boundaries, the +amount of memory affected may be greater than size. Use +host_page_size to find the current virtual page size. +

+A parent and a child task can share the same physical memory only if the +inheritance for the memory is set to VM_INHERIT_SHARE before +the child task is +created. Other than through the use of an external memory manager (see +vm_map), this is the only way that two tasks can share memory. +

+Note that all the threads within a task share the task's memory. +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_ADDRESS +
+The address is illegal or specifies a non-allocated region. +
+

RELATED INFORMATION

+

+Functions: +task_create, +vm_map, +vm_region, +norma_task_create. 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 @@ -

vm_machine_attribute

Function - Get/set the target memory region's special attributes.

SYNOPSIS

kern_return_t   vm_machine_attribute
                (vm_task_t                          target_task,
                 vm_address_t                           address,
                 vm_size_t                                 size,
                 vm_machine_attribute_t               attribute,
                 vm_machine_attribute_val_t               value);

PARAMETERS

target_task
[in task send right] The port for the task in whose address space the memory object is to be manipulated.

address
[in scalar] The starting address for the memory region. The granularity of rounding of this value to page boundaries is implementation dependent.

size
[in scalar] The number of bytes in the region. The granularity of rounding of this value to page boundaries is implementation dependent.

attribute
[in scalar] The name of the attribute to be get/set. Possible values are:

MATTR_CACHE
Cachability. Aside from the generic values listed below, the following special values are defined:

MATTR_VAL_CACHE_FLUSH
Flush from all caches

MATTR_VAL_DCACHE_FLUSH
Flush from data caches

MATTR_VAL_ICACHE_FLUSH
Flush from instruction caches

MATTR_MIGRATE
Migratability.

MATTR_REPLICATE
Replicability.

value
[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:

MATTR_VAL_OFF
Turn attribute off.

MATTR_VAL_ON
Turn attribute on.

MATTR_VAL_GET
No change, just return current value.

DESCRIPTION

The vm_machine_attribute function gets and sets special attributes of the memory region implemented by the underlying pmap module. These attributes are properties such as cachability, migratability and replicability. The behavior of this function is machine dependent.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_INVALID_ADDRESS
The address is illegal or specifies a non-allocated region.

RELATED INFORMATION

Functions: vm_wire. \ No newline at end of file +

vm_machine_attribute

+
+

+Function - Get/set the target memory region's special attributes. +

SYNOPSIS

+
+kern_return_t   vm_machine_attribute
+                (vm_task_t                          target_task,
+                 vm_address_t                           address,
+                 vm_size_t                                 size,
+                 vm_machine_attribute_t               attribute,
+                 vm_machine_attribute_val_t               value);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task in whose address space the +memory object is to be manipulated. +

+

address +
+[in scalar] +The starting address for the memory region. The granularity +of rounding of this value to page boundaries is implementation +dependent. +

+

size +
+[in scalar] +The number of bytes in the region. The granularity of +rounding of this value to page boundaries is implementation dependent. +

+

attribute +
+[in scalar] +The name of the attribute to be get/set. Possible values are: +
+

+

MATTR_CACHE +
+Cachability. Aside from the generic values listed below, the +following special values are defined: +
+

+

MATTR_VAL_CACHE_FLUSH +
+Flush from all caches +

+

MATTR_VAL_DCACHE_FLUSH +
+Flush from data caches +

+

MATTR_VAL_ICACHE_FLUSH +
+Flush from instruction caches +
+

+

MATTR_MIGRATE +
+Migratability. +

+

MATTR_REPLICATE +
+Replicability. +
+

+

value +
+[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: +
+

+

MATTR_VAL_OFF +
+Turn attribute off. +

+

MATTR_VAL_ON +
+Turn attribute on. +

+

MATTR_VAL_GET +
+No change, just return current value. +
+
+

DESCRIPTION

+

+The vm_machine_attribute function gets and sets special +attributes of the +memory region implemented by the underlying pmap module. These attributes +are properties such as cachability, migratability and replicability. +The behavior of this function is machine dependent. +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_ADDRESS +
+The address is illegal or specifies a non-allocated region. +
+

RELATED INFORMATION

+

+Functions: +vm_wire. 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 @@ -

vm_map

Function - Map the specified memory object to a region of virtual memory.

SYNOPSIS

kern_return_t   vm_map
                (vm_task_t                          target_task,
                 vm_address_t                           address,
                 vm_size_t                                 size,
                 vm_address_t                              mask,
                 boolean_t                             anywhere,
                 memory_object_t                  memory_object,
                 vm_offset_t                             offset,
                 boolean_t                                 copy,
                 vm_prot_t                       cur_protection,
                 vm_prot_t                       max_protection,
                 vm_inherit_t                       inheritance);

PARAMETERS

target_task
[in task send right] The port for the task in whose address space the memory object is to be mapped.

address
[pointer to in/out scalar] The starting address for the mapped object. The mapped object will start at the beginning of the page containing address. 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.

size
[in scalar] The number of bytes to allocate for the object. The kernel rounds this number up to an integral number of virtual pages.

mask
[in scalar] Alignment restrictions for starting address. Bits turned on in the mask will not be turned on in the starting address.

anywhere
[in scalar] Placement indicator. The valid values are:

TRUE
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 address.

FALSE
The kernel allocates the region starting at address unless that space is already allocated.

memory_object
[in memory-object send right] The port naming the memory object. If MEMORY_OBJECT_NULL is specified, the kernel allocates zero-filled memory, as with vm_allocate.

offset
[in scalar] An offset within the memory object, in bytes. The kernel maps address to the specified offset.

copy
[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.

cur_protection
[in scalar] The initial current protection for the region. Valid values are obtained by or'ing together the following values:

VM_PROT_READ
Allows read access.

VM_PROT_WRITE
Allows write access.

VM_PROT_EXECUTE
Allows execute access.

max_protection
[in scalar] The maximum protection for the region. Values are the same as for cur_protection.

inheritance
[in scalar] The initial inheritance attribute for the region. Valid values are:

VM_INHERIT_SHARE
Allows child tasks to share the region.

VM_INHERIT_COPY
Gives child tasks a copy of the region.

VM_INHERIT_NONE
Provides no access to the region for child tasks.

DESCRIPTION

The vm_map function maps a portion of the specified memory object into the virtual address space belonging to target_task. The target task can be the calling task or another task, identified by its task kernel port.

The portion of the memory object mapped is determined by offset and size. The kernel maps address to the offset, so that an access to the memory starts at the offset in the object.

The mask parameter specifies additional alignment restrictions on the kernel's selection of the starting address. Uses for this mask include:

  • Forcing the memory address alignment for a mapping to be the same as the alignment within the memory object.
  • Quickly finding the beginning of an allocated region by performing bit arithmetic on an address known to be in the region.
  • Emulating a larger virtual page size.

The cur_protection, max_protection, and inheritance 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 vm_inherit and vm_protect separately.

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 offset 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.

NOTES

vm_map allocates a region in a task's address space and maps the specified memory object to this region. vm_allocate allocates a zero-filled temporary region in a task's address space.

Before a memory object can be mapped, a port naming it must be acquired from the memory manager serving it.

This interface is machine word length specific because of the virtual address parameter.

CAUTIONS

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.

RETURN VALUES

KERN_NO_SPACE
There is not enough space in the task's address space to allocate the new region for the memory object.

KERN_PROTECTION_FAILURE
max_protection or cur_protection exceeds that permitted by memory_object.

KERN_INVALID_OBJECT
The memory manager failed to map the memory object.

RELATED INFORMATION

Functions: vm_allocate, vm_remap. \ No newline at end of file +

vm_map

+
+

+Function - Map the specified memory object to a region of virtual memory. +

SYNOPSIS

+
+kern_return_t   vm_map
+                (vm_task_t                          target_task,
+                 vm_address_t                           address,
+                 vm_size_t                                 size,
+                 vm_address_t                              mask,
+                 boolean_t                             anywhere,
+                 memory_object_t                  memory_object,
+                 vm_offset_t                             offset,
+                 boolean_t                                 copy,
+                 vm_prot_t                       cur_protection,
+                 vm_prot_t                       max_protection,
+                 vm_inherit_t                       inheritance);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task in whose address space the +memory object is to be mapped. +

+

address +
+[pointer to in/out scalar] +The starting address for the mapped object. +The mapped object will start at the beginning of the page containing +address. 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. +

+

size +
+[in scalar] +The number of bytes to allocate for the object. The kernel +rounds this number up to an integral number of virtual pages. +

+

mask +
+[in scalar] +Alignment restrictions for starting address. Bits turned on in +the mask will not be turned on in the starting address. +

+

anywhere +
+[in scalar] +Placement indicator. The valid values are: +
+

+

TRUE +
+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 address. +

+

FALSE +
+The kernel allocates the region starting at address unless that +space is already allocated. +
+

+

memory_object +
+[in memory-object send right] +The port naming the +memory object. If MEMORY_OBJECT_NULL is +specified, the kernel allocates zero-filled memory, as with vm_allocate. +

+

offset +
+[in scalar] +An offset within the memory object, in bytes. The kernel +maps address to the specified offset. +

+

copy +
+[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. +

+

cur_protection +
+[in scalar] +The initial current protection for the region. Valid values are +obtained by or'ing together the following values: +
+

+

VM_PROT_READ +
+Allows read access. +

+

VM_PROT_WRITE +
+Allows write access. +

+

VM_PROT_EXECUTE +
+Allows execute access. +
+

+

max_protection +
+[in scalar] +The maximum protection for the region. Values are the same +as for cur_protection. +

+

inheritance +
+[in scalar] +The initial inheritance attribute for the region. Valid values +are: +
+

+

VM_INHERIT_SHARE +
+Allows child tasks to share the region. +

+

VM_INHERIT_COPY +
+Gives child tasks a copy of the region. +

+

VM_INHERIT_NONE +
+Provides no access to the region for child tasks. +
+
+

DESCRIPTION

+

+The vm_map function maps a portion of the specified +memory object into the +virtual address space belonging to target_task. The target task +can be the calling +task or another task, identified by its task kernel port. +

+The portion of the memory object mapped is determined by offset +and size. The +kernel maps address to the offset, so that an access to the memory +starts at the offset in the object. +

+The mask parameter specifies additional alignment restrictions on +the kernel's selection of the starting address. Uses for this mask include: +

    +
  • +Forcing the memory address alignment for a mapping to be the same as the +alignment within the memory object. +
  • +Quickly finding the beginning of an allocated region by performing bit +arithmetic on an address known to be in the region. +
  • +Emulating a larger virtual page size. +
+

+The cur_protection, max_protection, and inheritance +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 vm_inherit and vm_protect separately. +

+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 offset +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. +

NOTES

+

+vm_map allocates a region in a task's address space +and maps the specified +memory object to this region. vm_allocate allocates +a zero-filled temporary +region in a task's address space. +

+Before a memory object can be mapped, a port naming it must be acquired from +the memory manager serving it. +

+This interface is machine word length specific because of the virtual address +parameter. +

CAUTIONS

+

+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. +

RETURN VALUES

+
+

+

KERN_NO_SPACE +
+There is not enough space in the task's address space to allocate the +new region for the memory object. +

+

KERN_PROTECTION_FAILURE +
+max_protection or cur_protection exceeds +that permitted by memory_object. +

+

KERN_INVALID_OBJECT +
+The memory manager failed to map the memory object. +
+

RELATED INFORMATION

+

+Functions: +vm_allocate, +vm_remap. 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 @@ -

vm_msync

Function - Synchronize the specified region of virtual memory.

SYNOPSIS

kern_return_t   vm_msync
                (vm_task_t                          target_task,
                 vm_address_t                           address,
                 vm_size_t                                 size,
                 target_task                         sync_flags);

PARAMETERS

target_task
[in task send right] The port for the task whose address space contains the region.

address
[in scalar] The starting address for the region.

size
[in scalar] The number of bytes in the region.

sync_flags
[in scalar] The bit-wise OR of flags affecting the synchronization. Specifying both VM_SYNC_SYNCHRONOUS and VM_SYNC_ASYNCHRONOUS is invalid.

VM_SYNC_INVALIDATE
Flushes pages in the range. Only precious pages are returned to the memory manager unless either VM_SYNC_SYNCHRONOUS or VM_SYNC_ASYNCHRONOUS is also set.

VM_SYNC_SYNCHRONOUS
Writes dirty and precious pages back to the memory manager, waits for pages to reach backing storage.

VM_SYNC_ASYNCHRONOUS
Writes dirty and precious pages back to the memory manager, returns without waiting for pages to reach backing storage.

DESCRIPTION

The vm_msync 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 (memory_object_synchronize). The client does not return from this call until the memory manager responds (to the kernel) with memory_object_synchronize_completed.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_INVALID_ADDRESS
The address is illegal or specifies a non-allocated region.

RELATED INFORMATION

Functions: memory_object_synchronize, memory_object_synchronize_completed. \ No newline at end of file +

vm_msync

+
+

+Function - Synchronize the specified region of virtual memory. +

SYNOPSIS

+
+kern_return_t   vm_msync
+                (vm_task_t                          target_task,
+                 vm_address_t                           address,
+                 vm_size_t                                 size,
+                 target_task                         sync_flags);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task whose address space contains +the region. +

+

address +
+[in scalar] +The starting address for the region. +

+

size +
+[in scalar] +The number of bytes in the region. +

+

sync_flags +
+[in scalar] +The bit-wise OR of flags affecting the synchronization. +Specifying both VM_SYNC_SYNCHRONOUS and +VM_SYNC_ASYNCHRONOUS is invalid. +
+

+

VM_SYNC_INVALIDATE +
+Flushes pages in the range. Only precious pages are returned to +the memory manager unless either VM_SYNC_SYNCHRONOUS or +VM_SYNC_ASYNCHRONOUS is also set. +

+

VM_SYNC_SYNCHRONOUS +
+Writes dirty and precious pages back to the memory manager, +waits for pages to reach backing storage. +

+

VM_SYNC_ASYNCHRONOUS +
+Writes dirty and precious pages back to the memory manager, +returns without waiting for pages to reach backing storage. +
+
+

DESCRIPTION

+

+The vm_msync 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 (memory_object_synchronize). +The client does not return from +this call until the memory manager responds (to the kernel) with +memory_object_synchronize_completed. +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_ADDRESS +
+The address is illegal or specifies a non-allocated region. +
+

RELATED INFORMATION

+

+Functions: +memory_object_synchronize, +memory_object_synchronize_completed. 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 @@ -

vm_protect

Function - Set access privilege attribute for a region of virtual memory.

SYNOPSIS

kern_return_t   vm_protect
                 (vm_task_t           target_task,
                  vm_address_t            address,
                  vm_size_t                  size,
                  boolean_t           set_maximum,
                  vm_prot_t        new_protection);

PARAMETERS

target_task
[in task send right] The port for the task whose address space contains the region.

address
[in scalar] The starting address for the region.

size
[in scalar] The number of bytes in the region.

set_maximum
[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.

new_protection
[in scalar] The new protection for the region. Valid values are obtained by or'ing together the following values:

VM_PROT_READ
Allows read access.

VM_PROT_WRITE
Allows write access.

VM_PROT_EXECUTE
Allows execute access.

DESCRIPTION

The vm_protect function sets access privileges for a region within the specified task's address space. The new_protection parameter specifies a combination of read, write, and execute accesses that are allowed (rather than prohibited).

The region starts at the beginning of the virtual page containing address; it ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory protected may be greater than size. Use host_page_size to find the current virtual page size.

The enforcement of virtual memory protection is machine-dependent. Nominally read access requires VM_PROT_READ permission, write access requires VM_PROT_WRITE permission, and execute access requires VM_PROT_EXECUTE permission. However, some combinations of access rights may not be supported. In particular, the kernel interface allows write access to require VM_PROT_READ and VM_PROT_WRITE permission and execute access to require VM_PROT_READ permission.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_PROTECTION_FAILURE
The new protection increased the current or maximum protection beyond the existing maximum protection.

KERN_INVALID_ADDRESS
The address is illegal or specifies a non-allocated region.

RELATED INFORMATION

Functions: host_page_size, vm_inherit, vm_region. \ No newline at end of file +

vm_protect

+
+

+Function - Set access privilege attribute for a region of virtual memory. +

SYNOPSIS

+
+kern_return_t   vm_protect
+                 (vm_task_t           target_task,
+                  vm_address_t            address,
+                  vm_size_t                  size,
+                  boolean_t           set_maximum,
+                  vm_prot_t        new_protection);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task whose address space contains +the region. +

+

address +
+[in scalar] +The starting address for the region. +

+

size +
+[in scalar] +The number of bytes in the region. +

+

set_maximum +
+[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. +

+

new_protection +
+[in scalar] +The new protection for the region. Valid values are obtained +by or'ing together the following values: +
+

+

VM_PROT_READ +
+Allows read access. +

+

VM_PROT_WRITE +
+Allows write access. +

+

VM_PROT_EXECUTE +
+Allows execute access. +
+
+

DESCRIPTION

+

+The vm_protect function sets access privileges for +a region within the specified +task's address space. +The new_protection parameter specifies a combination +of read, write, and +execute accesses that are allowed (rather than prohibited). +

+The region starts at the beginning of the virtual page containing +address; it ends +at the end of the virtual page containing address + +size - 1. Because of this +rounding to virtual page boundaries, the amount of memory protected may be +greater than size. Use host_page_size +to find the current virtual page size. +

+The enforcement of virtual memory protection is machine-dependent. +Nominally read access requires VM_PROT_READ permission, +write access requires +VM_PROT_WRITE permission, and execute access requires +VM_PROT_EXECUTE permission. However, some combinations +of access rights may not be +supported. In particular, the kernel interface allows write access to require +VM_PROT_READ and VM_PROT_WRITE permission and execute access to +require VM_PROT_READ permission. +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_PROTECTION_FAILURE +
+The new protection increased the current or maximum protection +beyond the existing maximum protection. +

+

KERN_INVALID_ADDRESS +
+The address is illegal or specifies a non-allocated region. +
+

RELATED INFORMATION

+

+Functions: +host_page_size, +vm_inherit, +vm_region. 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 @@ -

vm_read

Function - Read the specified range of target task's address space.

SYNOPSIS

kern_return_t   vm_read
                (vm_task_t                          target_task,
                 vm_address_t                           address,
                 vm_size_t                                 size,
                 size                                  data_out,
                 target_task                         data_count);

Overwrite form:

kern_return_t   vm_read_overwrite
                (vm_task_t                          target_task,
                 vm_address_t                           address,
                 vm_size_t                                 size,
                 pointer_t                              data_in,
                 target_task                         data_count);

PARAMETERS

target_task
[in task send right] The port for the task whose memory is to be read.

address
[in scalar] The address at which to start the read.

size
[in scalar] The number of bytes to read.

data_out
Out-pointer to dynamic array of bytes returned by the read.

data_in
In-pointer to array of bytes that will be overwritten with the data returned by the read.

data_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

DESCRIPTION

The vm_read and vm_read_overwrite functions read a portion of a task's virtual memory (they enable tasks to read other tasks' memory). The vm_read function returns the data in a dynamically allocated array of bytes; the vm_read_overwrite function places the data into a caller-specified buffer (the data_in parameter).

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_PROTECTION_FAILURE
Specified memory is valid, but does not permit reading.

KERN_INVALID_ADDRESS
The address is illegal or specifies a non-allocated region, or there are less than size bytes of data following the address, or the region specified by the data_in parameter cannot be written to.

RELATED INFORMATION

Functions: vm_copy, vm_deallocate, vm_write. \ No newline at end of file +

vm_read

+
+

+Function - Read the specified range of target task's address space. +

SYNOPSIS

+
+kern_return_t   vm_read
+                (vm_task_t                          target_task,
+                 vm_address_t                           address,
+                 vm_size_t                                 size,
+                 size                                  data_out,
+                 target_task                         data_count);
+
+ +

Overwrite form:

+
+kern_return_t   vm_read_overwrite
+                (vm_task_t                          target_task,
+                 vm_address_t                           address,
+                 vm_size_t                                 size,
+                 pointer_t                              data_in,
+                 target_task                         data_count);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task whose memory is to be read. +

+

address +
+[in scalar] +The address at which to start the read. +

+

size +
+[in scalar] +The number of bytes to read. +

+

data_out +
+Out-pointer to dynamic array of bytes returned by the read. +

+

data_in +
+In-pointer to array of bytes that will be overwritten with the data returned by the read. +

+

data_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +
+

DESCRIPTION

+

+The vm_read and vm_read_overwrite +functions read a portion of a task's virtual +memory (they enable tasks to read other tasks' memory). +The vm_read function returns the data in a dynamically +allocated array of bytes; the vm_read_overwrite function +places the data into a caller-specified buffer (the data_in +parameter). +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_PROTECTION_FAILURE +
+Specified memory is valid, but does not permit reading. +

+

KERN_INVALID_ADDRESS +
+The address is illegal or specifies a non-allocated region, or there are +less than size bytes of data following the address, or the region +specified by the data_in parameter cannot be written to. +
+

RELATED INFORMATION

+

+Functions: +vm_copy, +vm_deallocate, +vm_write. 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 @@ -

vm_region

Function - Return description of a virtual memory region.

SYNOPSIS

kern_return_t   vm_region
                 (vm_task_t                    target_task,
                  vm_address_t                     address,
                  vm_size_t                           size,
                  vm_region_flavor_t                flavor,
                  vm_region_info_t                    info,
                  mach_msg_type_number_t        info_count,
                  memory_object_name_t         object_name);

PARAMETERS

target_task
[in task send right] The port for the task whose address space contains the region.

address
[pointer to in/out scalar] The address at which to start looking for a region. The function returns the starting address actually used.

size
[out scalar] The number of bytes in the located region. The number converts to an integral number of virtual pages.

flavor
[in scalar] The type of information to be returned. Valid values are:

VM_REGION_BASIC_INFO
Basic information about the region (size, inheritance, etc.). This information is declared by the vm_region_basic_info structure.

info
[out structure] Returned region information.

info_count
[in/out scalar] On input, the maximum size of the buffer; on output, the size returned (in natural-sized units).

object_name
This parameter is no longer used.

DESCRIPTION

The vm_region function returns information on a region within the specified task's address space. The function begins looking at address 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 address.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_INVALID_ADDRESS
There is no region at or beyond the specified starting address.

RELATED INFORMATION

Functions: vm_allocate, vm_deallocate, vm_inherit, vm_protect, vm_behavior_set.

Data Structures: vm_region_basic_info. \ No newline at end of file +

vm_region

+
+

+Function - Return description of a virtual memory region. +

SYNOPSIS

+
+kern_return_t   vm_region
+                 (vm_task_t                    target_task,
+                  vm_address_t                     address,
+                  vm_size_t                           size,
+                  vm_region_flavor_t                flavor,
+                  vm_region_info_t                    info,
+                  mach_msg_type_number_t        info_count,
+                  memory_object_name_t         object_name);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task whose address space contains +the region. +

+

address +
+[pointer to in/out scalar] +The address at which to start looking for a +region. The function returns the starting address actually used. +

+

size +
+[out scalar] +The number of bytes in the located region. The number +converts to an integral number of virtual pages. +

+

flavor +
+[in scalar] +The type of information to be returned. Valid values are: +
+

+

VM_REGION_BASIC_INFO +
+Basic information about the region (size, inheritance, etc.). +This information is declared by the + vm_region_basic_info structure. +
+

+

info +
+[out structure] +Returned region information. +

+

info_count +
+[in/out scalar] +On input, the maximum size of the buffer; on output, the +size returned (in natural-sized units). +

+

object_name +
+ This parameter is no longer used. +
+

DESCRIPTION

+

+The vm_region function returns information on a region +within the specified +task's address space. +The function begins looking at address 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 address. +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_ADDRESS +
+There is no region at or beyond the specified starting address. +
+

RELATED INFORMATION

+

+Functions: +vm_allocate, +vm_deallocate, +vm_inherit, +vm_protect, +vm_behavior_set. +

+Data Structures: +vm_region_basic_info. 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 @@ -

vm_region_basic_info

Structure - Defines the attributes of a task's memory region.

SYNOPSIS

struct vm_region_basic_info
{
       vm_prot_t             protection;
       vm_prot_t         max_protection;
       vm_inherit_t         inheritance;
       boolean_t                 shared;
       boolean_t               reserved;
       vm_offset_t               offset;
       vm_behavior_t           behavior;
       unsigned short  user_wired_count;
};

typedef struct vm_region_basic_info* vm_region_basic_info_t;

FIELDS

protection
The current protection for the region.

max_protection
The maximum protection allowed for the region.

inheritance
The inheritance attribute for the region.

shared
Shared indicator. If true, the region is shared by another task. If false, the region is not shared.

reserved
If true the region is protected from random allocation.

offset
The region's offset into the memory object. The region begins at this offset.

behavior
Expected reference pattern for the memory. Valid values are:

VM_BEHAVIOR_DEFAULT
The system's default behavior.

VM_BEHAVIOR_RANDOM
No particular order expected.

VM_BEHAVIOR_SEQUENTIAL
Forward sequential order.

VM_BEHAVIOR_RSEQNTL
Reverse sequential order.

DESCRIPTION

The vm_region_basic_info structure defines the attributes of a memory region returned by vm_region.

RELATED INFORMATION

Functions: vm_region, vm_inherit, vm_protect. \ No newline at end of file +

vm_region_basic_info

+
+

+Structure - Defines the attributes of a task's memory region. +

SYNOPSIS

+
+struct vm_region_basic_info
+{
+       vm_prot_t             protection;
+       vm_prot_t         max_protection;
+       vm_inherit_t         inheritance;
+       boolean_t                 shared;
+       boolean_t               reserved;
+       vm_offset_t               offset;
+       vm_behavior_t           behavior;
+       unsigned short  user_wired_count;
+};
+
+typedef struct vm_region_basic_info* vm_region_basic_info_t;
+
+

FIELDS

+
+
protection +
+The current protection for the region. +

+

max_protection +
+The maximum protection allowed for the region. +

+

inheritance +
+The inheritance attribute for the region. +

+

shared +
+Shared indicator. If true, the region is shared by another task. If false, +the region is not shared. +

+

reserved +
+If true the region is protected from random allocation. +

+

offset +
+The region's offset into the memory object. The region begins at this +offset. +

+

behavior +
+Expected reference pattern for the memory. Valid values are: +
+

+

VM_BEHAVIOR_DEFAULT +
+The system's default behavior. +

+

VM_BEHAVIOR_RANDOM +
+No particular order expected. +

+

VM_BEHAVIOR_SEQUENTIAL +
+Forward sequential order. +

+

VM_BEHAVIOR_RSEQNTL +
+Reverse sequential order. +
+
+

DESCRIPTION

+

+The vm_region_basic_info structure defines the attributes +of a memory region returned by vm_region. +

RELATED INFORMATION

+

+Functions: +vm_region, +vm_inherit, +vm_protect. 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 @@ -

vm_remap

Function - Map memory objects in one task's address space to that of another task's.

SYNOPSIS

kern_return_t   vm_remap
                 (mach_port_t	           target_task,
                  vm_address_t	        target_address,
                  vm_size_t	                  size,
                  vm_address_t	                  mask,
                  boolean_t	              anywhere,
                  mach_port_t	           source_task,
                  vm_address_t	        source_address,
                  boolean_t	                  copy,
                  vm_prot_t	        cur_protection,
                  vm_prot_t	        max_protection,
                  vm_inherit_t            inheritance);

PARAMETERS

target_task
[in task send right] The port for the task in whose address space the memory is to be mapped.

target_address
[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 target_address. 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.

size
[in scalar] The number of bytes to map. The kernel rounds this number up to an integral number of virtual pages.

mask
[in scalar] Alignment restrictions for starting address. Bits turned on in the mask will not be turned on in the starting address.

anywhere
[in scalar] Placement indicator. The valid values are:

TRUE
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 address.

FALSE
The kernel allocates the region starting at address unless that space is already allocated.

source_task
[in task send right] The port for the task whose address space is to be mapped.

source_address
[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 source_address. If not enough memory exists following the address, the kernel does not map the memory.

copy
[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.

cur_protection
[out scalar] The most restrictive current protection for the memory in the region. Valid values are obtained by or'ing together the following values:

VM_PROT_READ
Allows read access.

VM_PROT_WRITE
Allows write access.

VM_PROT_EXECUTE
Allows execute access.

max_protection
[out scalar] The most restrictive maximum protection for the memory in the region. Values are the same as for cur_protection.

inheritance
[in scalar] The initial inheritance attribute for the region. Valid values are:

VM_INHERIT_SHARE
Allows child tasks to share the region.

VM_INHERIT_COPY
Gives child tasks a copy of the region.

VM_INHERIT_NONE
Provides no access to the region for child tasks.

DESCRIPTION

The vm_remap function maps the memory objects underlying a portion of the specified source_task's virtual address space into the address space belonging to target_task. 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 vm_map 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 target_address, so that access to target_address is as if the source task accessed its source_address.

The mask parameter specifies additional alignment restrictions on the kernel's selection of the starting address. Uses for this mask include:

  • Forcing the memory address alignment for a mapping to be the same as the alignment within the source task.
  • Quickly finding the beginning of an allocated region by performing bit arithmetic on an address known to be in the region.
  • Emulating a larger virtual page size.
The cur_protection and max_protection 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.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_NO_SPACE
There is not enough space in the task's address space to allocate the new region for the memory object.

KERN_PROTECTION_FAILURE
Specified memory is valid, but the backing memory manager is not permitted by the requesting task.

RELATED INFORMATION

Functions: vm_map, vm_read, vm_write. \ No newline at end of file +

vm_remap

+
+

+Function - Map memory objects in one task's address space to that of another task's. +

SYNOPSIS

+
+kern_return_t   vm_remap
+                 (mach_port_t	           target_task,
+                  vm_address_t	        target_address,
+                  vm_size_t	                  size,
+                  vm_address_t	                  mask,
+                  boolean_t	              anywhere,
+                  mach_port_t	           source_task,
+                  vm_address_t	        source_address,
+                  boolean_t	                  copy,
+                  vm_prot_t	        cur_protection,
+                  vm_prot_t	        max_protection,
+                  vm_inherit_t            inheritance);
+
+

PARAMETERS

+
+
target_task +
+[in task send right] +The port for the task in whose address space the +memory is to be mapped. +

+

target_address +
+[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 target_address. 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. +

+

size +
+[in scalar] +The number of bytes to map. The kernel rounds this number +up to an integral number of virtual pages. +

+

mask +
+[in scalar] +Alignment restrictions for starting address. Bits turned on in +the mask will not be turned on in the starting address. +

+

anywhere +
+[in scalar] +Placement indicator. + The valid values are: +
+

+

TRUE +
+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 address. +

+

FALSE +
+The kernel allocates the region starting at address unless that +space is already allocated. +
+

+

source_task +
+[in task send right] +The port for the task whose address space is to be +mapped. +

+

source_address +
+[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 source_address. If not enough memory exists +following the address, the kernel does not map the memory. +

+

copy +
+[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. +

+

cur_protection +
+[out scalar] +The most restrictive current protection for the memory in +the region. Valid values are obtained by or'ing together the following +values: +
+

+

VM_PROT_READ +
+Allows read access. +

+

VM_PROT_WRITE +
+Allows write access. +

+

VM_PROT_EXECUTE +
+Allows execute access. +
+

+

max_protection +
+[out scalar] +The most restrictive maximum protection for the memory +in the region. Values are the same as for cur_protection. +

+

inheritance +
+[in scalar] +The initial inheritance attribute for the region. Valid values +are: +
+

+

VM_INHERIT_SHARE +
+Allows child tasks to share the region. +

+

VM_INHERIT_COPY +
+Gives child tasks a copy of the region. +

+

VM_INHERIT_NONE +
+Provides no access to the region for child tasks. +
+
+

DESCRIPTION

+

+The vm_remap function maps the memory objects underlying +a portion of the +specified source_task's virtual address space into the address +space belonging to +target_task. 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 vm_map 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 target_address, so that access to target_address +is as if the source task +accessed its source_address. +

+The mask parameter +specifies additional alignment restrictions on the kernel's +selection of the starting address. Uses for this mask include: +

    +
  • +Forcing the memory address alignment for a mapping to be the same as the +alignment within the source task. +
  • +Quickly finding the beginning of an allocated region by performing bit +arithmetic on an address known to be in the region. +
  • +Emulating a larger virtual page size. +
+The cur_protection and max_protection 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. +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_NO_SPACE +
+There is not enough space in the task's address space to allocate the +new region for the memory object. +

+

KERN_PROTECTION_FAILURE +
+Specified memory is valid, but the backing memory manager is +not permitted by the requesting task. +
+

RELATED INFORMATION

+

+Functions: +vm_map, +vm_read, +vm_write. 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 @@ -

vm_statistics

Structure - Defines statistics for the kernel's use of virtual memory.

SYNOPSIS

struct vm_statistics
{
       integer_t       free_count;
       integer_t       active_count;
       integer_t       inactive_count;
       integer_t       wire_count;
       integer_t       zero_fill_count;
       integer_t       reactivations;
       integer_t       pageins;
       integer_t       pageouts;
       integer_t       faults;
       integer_t       cow_faults;
       integer_t       lookups;
       integer_t       hits;
};

typedef struct vm_statistics* vm_statistics_t;

FIELDS

free_count
The total number of free pages in the system.

active_count
The total number of pages currently in use and pageable.

inactive_count
The number of inactive pages.

wire_count
The number of pages that are wired in memory and cannot be paged out.

zero_fill_count
The number of zero-fill pages.

reactivations
The number of reactivated pages.

pageins
The number of requests for pages from a pager (such as the i-node pager).

pageouts
The number of pages that have been paged out.

faults
The number of times the vm_fault routine has been called.

cow_faults
The number of copy-on-write faults.

lookups
The number of object cache lookups.

hits
The number of object cache hits.

DESCRIPTION

The vm_statistics structure defines the statistics available on the kernel's use of virtual memory. The statistics record virtual memory usage since the kernel was booted.

For related information for a specific task, see the task_basic_info structure.

NOTES

This structure is machine word length specific because of the memory sizes returned.

RELATED INFORMATION

Functions: task_info, host_page_size.

Data Structures: task_basic_info. \ No newline at end of file +

vm_statistics

+
+

+Structure - Defines statistics for the kernel's use of virtual memory. +

SYNOPSIS

+
+struct vm_statistics
+{
+       integer_t       free_count;
+       integer_t       active_count;
+       integer_t       inactive_count;
+       integer_t       wire_count;
+       integer_t       zero_fill_count;
+       integer_t       reactivations;
+       integer_t       pageins;
+       integer_t       pageouts;
+       integer_t       faults;
+       integer_t       cow_faults;
+       integer_t       lookups;
+       integer_t       hits;
+};
+
+typedef struct vm_statistics* vm_statistics_t;
+
+

FIELDS

+
+
free_count +
+The total number of free pages in the system. +

+

active_count +
+The total number of pages currently in use and pageable. +

+

inactive_count +
+The number of inactive pages. +

+

wire_count +
+The number of pages that are wired in memory and cannot be paged +out. +

+

zero_fill_count +
+The number of zero-fill pages. +

+

reactivations +
+The number of reactivated pages. +

+

pageins +
+The number of requests for pages from a pager (such as the i-node +pager). +

+

pageouts +
+The number of pages that have been paged out. +

+

faults +
+The number of times the vm_fault routine has been called. +

+

cow_faults +
+The number of copy-on-write faults. +

+

lookups +
+The number of object cache lookups. +

+

hits +
+The number of object cache hits. +
+

DESCRIPTION

+

+The vm_statistics structure defines the statistics +available on the kernel's use of +virtual memory. The statistics record virtual memory usage since +the kernel was booted. +

+For related information for a specific task, see the task_basic_info +structure. +

NOTES

+

+This structure is machine word length specific because of the memory sizes +returned. +

RELATED INFORMATION

+

+Functions: +task_info, +host_page_size. +

+Data Structures: +task_basic_info. + 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 @@ -

vm_wire

Function - Modify the target region's paging characteristics.

SYNOPSIS

kern_return_t   vm_wire
                (host_priv_t                               host,
                 vm_task_t                          target_task,
                 vm_address_t                           address,
                 vm_size_t                                 size,
                 vm_prot_t                         wired_access);

PARAMETERS

host
[in host-control send right] The control port for the host for which information is to be obtained.

target_task
[in task send right] The port for the task whose address space contains the region.

address
[in scalar] The starting address for the region.

size
[in scalar] The number of bytes in the region.

wired_access
[in scalar] The pageability of the region. The following values cause the region to be wired and protected as specified (values may be combined):
VM_PROT_READ
VM_PROT_WRITE
VM_PROT_execute

The following value causes the region to be unwired (made pageable):

VM_PROT_NONE

DESCRIPTION

The vm_wire function sets the pageability privileges for a region within the specified task's address space. wired_access 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 wired_access 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.

The region starts at the beginning of the virtual page containing address; it ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than size. Use host_page_size to find the current virtual page size.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_INVALID_ADDRESS
The address is illegal or specifies a non-allocated region.

RELATED INFORMATION

Functions: thread_wire. \ No newline at end of file +

vm_wire

+
+

+Function - Modify the target region's paging characteristics. +

SYNOPSIS

+
+kern_return_t   vm_wire
+                (host_priv_t                               host,
+                 vm_task_t                          target_task,
+                 vm_address_t                           address,
+                 vm_size_t                                 size,
+                 vm_prot_t                         wired_access);
+
+

PARAMETERS

+
+

+

host +
+[in host-control send right] +The control port for the host for which +information is to be obtained. +

+

target_task +
+[in task send right] +The port for the task whose address space contains +the region. +

+

address +
+[in scalar] +The starting address for the region. +

+

size +
+[in scalar] +The number of bytes in the region. +

+

wired_access +
+[in scalar] +The pageability of the region. The following values cause +the region to be wired and protected as specified +(values may be combined): +
+
VM_PROT_READ +
VM_PROT_WRITE +
VM_PROT_execute +
+

+The following value causes the region to be unwired (made pageable): +

+
VM_PROT_NONE +
+
+

DESCRIPTION

+

+The vm_wire function sets the pageability privileges +for a region within the +specified task's address space. wired_access 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 wired_access 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. +

+The region starts at the beginning of the virtual page containing +address; it ends at the end of the virtual page containing +address + size - 1. Because of this +rounding to virtual page boundaries, the amount of memory affected may be +greater than size. Use host_page_size to find the current +virtual page size. +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_INVALID_ADDRESS +
+The address is illegal or specifies a non-allocated region. +
+

RELATED INFORMATION

+

+Functions: +thread_wire. 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 @@ -

vm_write

Function - Write data to the specified address in the target task's address space.

SYNOPSIS

kern_return_t   vm_write
                (vm_task_t                          target_task,
                 vm_address_t                           address,
                 pointer_t                                 data,
                 mach_msg_type_number_t              data_count);

PARAMETERS

target_task
[in task send right] The port for the task whose memory is to be written.

address
[in scalar] The address at which to start the write.

data
[pointer to page aligned in array of bytes] An array of data to be written.

data_count
[in scalar] The number of bytes in the array.

DESCRIPTION

The vm_write function writes an array of data to a task's virtual memory. It allows one task to write to another task's memory.

The result of vm_write is as if target_task had directly written into the set of pages. Hence, target_task must have write permission to the pages.

NOTES

This interface is machine word length specific because of the virtual address parameter.

RETURN VALUES

KERN_PROTECTION_FAILURE
Specified memory is valid, but does not permit writing.

KERN_INVALID_ADDRESS
The address is illegal or specifies a non-allocated region.

RELATED INFORMATION

Functions: vm_copy, vm_protect, vm_read, host_page_size. \ No newline at end of file +

vm_write

+
+

+Function - Write data to the specified address in the target task's address space. +

SYNOPSIS

+
+kern_return_t   vm_write
+                (vm_task_t                          target_task,
+                 vm_address_t                           address,
+                 pointer_t                                 data,
+                 mach_msg_type_number_t              data_count);
+
+

PARAMETERS

+
+

+

target_task +
+[in task send right] +The port for the task whose memory is to be +written. +

+

address +
+[in scalar] +The address at which to start the write. +

+

data +
+[pointer to page aligned in array of bytes] +An array of data to be +written. +

+

data_count +
+[in scalar] +The number of bytes in the array. +
+

DESCRIPTION

+

+The vm_write function writes an array of data to a +task's virtual memory. It +allows one task to write to another task's memory. +

+The result of vm_write is as if target_task had directly +written into the set of +pages. Hence, target_task must have write permission to the pages. +

NOTES

+

+This interface is machine word length specific because of the virtual address +parameter. +

RETURN VALUES

+
+

+

KERN_PROTECTION_FAILURE +
+Specified memory is valid, but does not permit writing. +

+

KERN_INVALID_ADDRESS +
+The address is illegal or specifies a non-allocated region. +
+

RELATED INFORMATION

+

+Functions: +vm_copy, +vm_protect, +vm_read, +host_page_size. 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,