[apple/xnu.git] / osfmk / kern / kern_types.h

/*
 * Copyright (c) 2000-2007 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 * 
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
/*
 * @OSF_COPYRIGHT@
 */

#ifndef	_KERN_KERN_TYPES_H_
#define	_KERN_KERN_TYPES_H_

#include <stdint.h>
#include <mach/mach_types.h>
#include <mach/machine/vm_types.h>

#ifdef	KERNEL_PRIVATE

#ifndef	MACH_KERNEL_PRIVATE

struct zone ;

#ifndef __LP64__
struct wait_queue { unsigned int opaque[2]; uintptr_t opaquep[2]; } ;
#else
struct wait_queue { unsigned char opaque[32]; };
#endif

#endif	/* MACH_KERNEL_PRIVATE */

typedef struct zone			*zone_t;
#define		ZONE_NULL			((zone_t) 0)

typedef struct wait_queue		*wait_queue_t;
#define		WAIT_QUEUE_NULL 	((wait_queue_t) 0)
#define 		SIZEOF_WAITQUEUE	sizeof(struct wait_queue)

typedef vm_offset_t			ipc_kobject_t;
#define		IKO_NULL			((ipc_kobject_t) 0)

#endif	/* KERNEL_PRIVATE */

typedef	void *event_t;		/* wait event */
#define		NO_EVENT			((event_t) 0)

typedef uint64_t event64_t;		/* 64 bit wait event */
#define		NO_EVENT64		((event64_t) 0)
#define		CAST_EVENT64_T(a_ptr)	((event64_t)((uintptr_t)(a_ptr)))

/*
 *	Possible wait_result_t values.
 */
typedef int wait_result_t;
#define THREAD_WAITING		-1		/* thread is waiting */
#define THREAD_AWAKENED		0		/* normal wakeup */
#define THREAD_TIMED_OUT	1		/* timeout expired */
#define THREAD_INTERRUPTED	2		/* aborted/interrupted */
#define THREAD_RESTART		3		/* restart operation entirely */
#define THREAD_NOT_WAITING      10              /* thread didn't need to wait */

typedef	void (*thread_continue_t)(void *, wait_result_t);
#define	THREAD_CONTINUE_NULL	((thread_continue_t) 0)

/*
 * Interruptible flag for waits.
 *
 * THREAD_UNINT: Uninterruptible wait
 *   Wait will only end when someone explicitly wakes up the thread, or if the
 *   wait timeout expires.
 *
 *   Use this state if the system as a whole cannot recover from a thread being
 *   interrupted out of the wait.
 *
 * THREAD_INTERRUPTIBLE:
 *    Wait will end if someone explicitly wakes up the thread, the wait timeout
 *    expires,  or the current thread is being terminated.
 *
 *    This value can be used when your operation may not be cleanly restartable
 *    for the current process or thread (i.e. the loss of state would be only visible
 *    to the current client).  Since the thread is exiting anyways, you're willing
 *    to cut the operation short.  The system as a whole must be able to cleanly
 *    deal with the interruption (i.e. remain in a consistent and recoverable state).
 *
 * THREAD_ABORTSAFE:
 *    Wait will end if someone explicitly wakes up the thread, the wait timeout
 *    expires, the current thread is being terminated, if any signal arrives for
 *    the task, or thread_abort_safely() is called on the thread.
 *
 *    Using this value means that you are willing to be interrupted in the face
 *    of any user signal, and safely rewind the thread back to the user/kernel
 *    boundary.  Many syscalls will try to restart the operation they were performing
 *    after the signal has been handled.
 *
 *    You must provide this value for any unbounded wait - otherwise you will
 *    pend user signals forever.
 *
 * Thread interrupt mask:
 *
 *   The current maximum interruptible state for the thread, as set by
 *   thread_interrupt_level(), will limit the conditions that will cause a wake.
 *   This is useful for code that can't be interrupted to set before calling code
 *   that doesn't know that.
 *
 * Thread termination vs safe abort:
 *
 *    Termination abort: thread_abort(), thread_terminate()
 *
 *    A termination abort is sticky.  Once a thread is marked for termination, every
 *    THREAD_INTERRUPTIBLE wait will return immediately with THREAD_INTERRUPTED
 *    until the thread successfully exits.
 *
 *    Safe abort: thread_abort_safely()
 *
 *    A safe abort is not sticky.  The current wait, (or the next wait if the thread
 *    is not currently waiting) will be interrupted, but then the abort condition is cleared.
 *    The next wait will sleep as normal. Safe aborts only have a single effect.
 *
 *    The path back to the user/kernel boundary must not make any further unbounded
 *    wait calls. The waiter should detect the THREAD_INTERRUPTED return code
 *    from an ABORTSAFE wait and return an error code that causes its caller
 *    to understand that the current operation has been interrupted, and its
 *    caller should return a similar error code, and so on until the
 *    user/kernel boundary is reached.  For Mach, the error code is usually KERN_ABORTED,
 *    for BSD it is EINTR.
 *
 *    Debuggers rely on the safe abort mechanism - a signaled thread must return to
 *    the AST at the user/kernel boundary for the debugger to finish attaching.
 *
 *    No wait/block will ever disappear a thread out from under the waiter. The block
 *    call will always either return or call the passed in continuation.
 */
typedef int wait_interrupt_t;
#define THREAD_UNINT			0		/* not interruptible      */
#define THREAD_INTERRUPTIBLE	1		/* may not be restartable */
#define THREAD_ABORTSAFE		2		/* abortable safely       */

typedef int wait_timeout_urgency_t;
#define TIMEOUT_URGENCY_SYS_NORMAL	0x00		/* use default leeway thresholds for system */
#define TIMEOUT_URGENCY_SYS_CRITICAL	0x01		/* use critical leeway thresholds for system */
#define TIMEOUT_URGENCY_SYS_BACKGROUND	0x02		/* use background leeway thresholds for system */

#define TIMEOUT_URGENCY_USER_MASK	0x10		/* mask to identify user timeout urgency classes */
#define TIMEOUT_URGENCY_USER_NORMAL	0x10		/* use default leeway thresholds for user */
#define TIMEOUT_URGENCY_USER_CRITICAL	0x11		/* use critical leeway thresholds for user */
#define TIMEOUT_URGENCY_USER_BACKGROUND	0x12		/* use background leeway thresholds for user */

#define TIMEOUT_URGENCY_MASK		0x13		/* mask to identify timeout urgency */

#define TIMEOUT_URGENCY_LEEWAY		0x20		/* don't ignore provided leeway value */

#define TIMEOUT_URGENCY_FIRST_AVAIL	0x40		/* first available bit outside of urgency mask/leeway */

#ifdef	KERNEL_PRIVATE

#ifdef	MACH_KERNEL_PRIVATE

#include <kern/misc_protos.h>
typedef  struct clock			*clock_t;

typedef struct mig_object		*mig_object_t;
#define MIG_OBJECT_NULL			((mig_object_t) 0)

typedef struct mig_notify		*mig_notify_t;
#define MIG_NOTIFY_NULL 		((mig_notify_t) 0)

typedef struct pset_node		*pset_node_t;
#define PSET_NODE_NULL			((pset_node_t) 0)

typedef struct affinity_set		*affinity_set_t;
#define AFFINITY_SET_NULL		((affinity_set_t) 0)

typedef struct run_queue               *run_queue_t;
#define RUN_QUEUE_NULL                 ((run_queue_t) 0)

typedef struct grrr_run_queue               *grrr_run_queue_t;
#define GRRR_RUN_QUEUE_NULL                 ((grrr_run_queue_t) 0)

typedef struct grrr_group					*grrr_group_t;
#define GRRR_GROUP_NULL						((grrr_group_t) 0)

#else	/* MACH_KERNEL_PRIVATE */

struct wait_queue_set ;
struct _wait_queue_link ;

#endif	/* MACH_KERNEL_PRIVATE */

typedef struct wait_queue_set	*wait_queue_set_t;
#define WAIT_QUEUE_SET_NULL 	((wait_queue_set_t)0)
#define SIZEOF_WAITQUEUE_SET	wait_queue_set_size()

typedef struct _wait_queue_link	*wait_queue_link_t;
#define WAIT_QUEUE_LINK_NULL	((wait_queue_link_t)0)
#define SIZEOF_WAITQUEUE_LINK	wait_queue_link_size()

/* legacy definitions - going away */
struct wait_queue_sub ;
typedef struct wait_queue_sub	*wait_queue_sub_t;
#define WAIT_QUEUE_SUB_NULL 	((wait_queue_sub_t)0)
#define SIZEOF_WAITQUEUE_SUB	wait_queue_set_size()

#endif	/* KERNEL_PRIVATE */

#endif	/* _KERN_KERN_TYPES_H_ */
Commit	Line	Data
1c79356b	1	/*
2d21ac55	2	* Copyright (c) 2000-2007 Apple Inc. All rights reserved.
1c79356b	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
1c79356b	5	*
2d21ac55 A	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. The rights granted to you under the License
	10	* may not be used to create, or enable the creation or redistribution of,
	11	* unlawful or unlicensed copies of an Apple operating system, or to
	12	* circumvent, violate, or enable the circumvention or violation of, any
	13	* terms of an Apple operating system software license agreement.
8f6c56a5	14	*
2d21ac55 A	15	* Please obtain a copy of the License at
	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
	17	*
	18	* The Original Code and all software distributed under the License are
	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	22	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	* Please see the License for the specific language governing rights and
	24	* limitations under the License.
8f6c56a5	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b A	27	*/
	28	/*
	29	* @OSF_COPYRIGHT@
	30	*/
	31
	32	#ifndef _KERN_KERN_TYPES_H_
	33	#define _KERN_KERN_TYPES_H_
	34
0b4e3aa0	35	#include <stdint.h>
9bccf70c	36	#include <mach/mach_types.h>
1c79356b	37	#include <mach/machine/vm_types.h>
9bccf70c	38
91447636	39	#ifdef KERNEL_PRIVATE
1c79356b	40
91447636	41	#ifndef MACH_KERNEL_PRIVATE
9bccf70c	42
1c79356b	43	struct zone ;
9bccf70c	44
b0d623f7	45	#ifndef __LP64__
91447636	46	struct wait_queue { unsigned int opaque[2]; uintptr_t opaquep[2]; } ;
b0d623f7 A	47	#else
	48	struct wait_queue { unsigned char opaque[32]; };
	49	#endif
9bccf70c	50
91447636	51	#endif /* MACH_KERNEL_PRIVATE */
1c79356b	52
9bccf70c A	53	typedef struct zone *zone_t;
	54	#define ZONE_NULL ((zone_t) 0)
	55
	56	typedef struct wait_queue *wait_queue_t;
	57	#define WAIT_QUEUE_NULL ((wait_queue_t) 0)
	58	#define SIZEOF_WAITQUEUE sizeof(struct wait_queue)
	59
	60	typedef vm_offset_t ipc_kobject_t;
	61	#define IKO_NULL ((ipc_kobject_t) 0)
	62
91447636 A	63	#endif /* KERNEL_PRIVATE */
91447636 A	64
9bccf70c A	65	typedef void event_t; / wait event */
	66	#define NO_EVENT ((event_t) 0)
	67
	68	typedef uint64_t event64_t; /* 64 bit wait event */
	69	#define NO_EVENT64 ((event64_t) 0)
cf7d32b8	70	#define CAST_EVENT64_T(a_ptr) ((event64_t)((uintptr_t)(a_ptr)))
9bccf70c A	71
	72	/*
	73	* Possible wait_result_t values.
	74	*/
	75	typedef int wait_result_t;
	76	#define THREAD_WAITING -1 /* thread is waiting */
	77	#define THREAD_AWAKENED 0 /* normal wakeup */
	78	#define THREAD_TIMED_OUT 1 /* timeout expired */
	79	#define THREAD_INTERRUPTED 2 /* aborted/interrupted */
	80	#define THREAD_RESTART 3 /* restart operation entirely */
b0d623f7	81	#define THREAD_NOT_WAITING 10 /* thread didn't need to wait */
9bccf70c	82
91447636	83	typedef void (thread_continue_t)(void , wait_result_t);
9bccf70c A	84	#define THREAD_CONTINUE_NULL ((thread_continue_t) 0)
	85
	86	/*
	87	* Interruptible flag for waits.
39236c6e A	88	*
	89	* THREAD_UNINT: Uninterruptible wait
	90	* Wait will only end when someone explicitly wakes up the thread, or if the
	91	* wait timeout expires.
	92	*
	93	* Use this state if the system as a whole cannot recover from a thread being
	94	* interrupted out of the wait.
	95	*
	96	* THREAD_INTERRUPTIBLE:
	97	* Wait will end if someone explicitly wakes up the thread, the wait timeout
	98	* expires, or the current thread is being terminated.
	99	*
	100	* This value can be used when your operation may not be cleanly restartable
	101	* for the current process or thread (i.e. the loss of state would be only visible
	102	* to the current client). Since the thread is exiting anyways, you're willing
	103	* to cut the operation short. The system as a whole must be able to cleanly
	104	* deal with the interruption (i.e. remain in a consistent and recoverable state).
	105	*
	106	* THREAD_ABORTSAFE:
	107	* Wait will end if someone explicitly wakes up the thread, the wait timeout
	108	* expires, the current thread is being terminated, if any signal arrives for
	109	* the task, or thread_abort_safely() is called on the thread.
	110	*
	111	* Using this value means that you are willing to be interrupted in the face
	112	* of any user signal, and safely rewind the thread back to the user/kernel
	113	* boundary. Many syscalls will try to restart the operation they were performing
	114	* after the signal has been handled.
	115	*
	116	* You must provide this value for any unbounded wait - otherwise you will
	117	* pend user signals forever.
	118	*
	119	* Thread interrupt mask:
	120	*
	121	* The current maximum interruptible state for the thread, as set by
	122	* thread_interrupt_level(), will limit the conditions that will cause a wake.
	123	* This is useful for code that can't be interrupted to set before calling code
	124	* that doesn't know that.
	125	*
	126	* Thread termination vs safe abort:
	127	*
	128	* Termination abort: thread_abort(), thread_terminate()
	129	*
	130	* A termination abort is sticky. Once a thread is marked for termination, every
	131	* THREAD_INTERRUPTIBLE wait will return immediately with THREAD_INTERRUPTED
	132	* until the thread successfully exits.
	133	*
	134	* Safe abort: thread_abort_safely()
	135	*
	136	* A safe abort is not sticky. The current wait, (or the next wait if the thread
	137	* is not currently waiting) will be interrupted, but then the abort condition is cleared.
	138	* The next wait will sleep as normal. Safe aborts only have a single effect.
	139	*
	140	* The path back to the user/kernel boundary must not make any further unbounded
	141	* wait calls. The waiter should detect the THREAD_INTERRUPTED return code
	142	* from an ABORTSAFE wait and return an error code that causes its caller
	143	* to understand that the current operation has been interrupted, and its
	144	* caller should return a similar error code, and so on until the
	145	* user/kernel boundary is reached. For Mach, the error code is usually KERN_ABORTED,
	146	* for BSD it is EINTR.
	147	*
	148	* Debuggers rely on the safe abort mechanism - a signaled thread must return to
	149	* the AST at the user/kernel boundary for the debugger to finish attaching.
	150	*
	151	* No wait/block will ever disappear a thread out from under the waiter. The block
152	* call will always either return or call the passed in continuation.
9bccf70c A	153	*/
	154	typedef int wait_interrupt_t;
	155	#define THREAD_UNINT 0 /* not interruptible */
	156	#define THREAD_INTERRUPTIBLE 1 /* may not be restartable */
	157	#define THREAD_ABORTSAFE 2 /* abortable safely */
	158
39236c6e A	159	typedef int wait_timeout_urgency_t;
	160	#define TIMEOUT_URGENCY_SYS_NORMAL 0x00 /* use default leeway thresholds for system */
	161	#define TIMEOUT_URGENCY_SYS_CRITICAL 0x01 /* use critical leeway thresholds for system */
	162	#define TIMEOUT_URGENCY_SYS_BACKGROUND 0x02 /* use background leeway thresholds for system */
	163
	164	#define TIMEOUT_URGENCY_USER_MASK 0x10 /* mask to identify user timeout urgency classes */
	165	#define TIMEOUT_URGENCY_USER_NORMAL 0x10 /* use default leeway thresholds for user */
	166	#define TIMEOUT_URGENCY_USER_CRITICAL 0x11 /* use critical leeway thresholds for user */
	167	#define TIMEOUT_URGENCY_USER_BACKGROUND 0x12 /* use background leeway thresholds for user */
	168
	169	#define TIMEOUT_URGENCY_MASK 0x13 /* mask to identify timeout urgency */
	170
	171	#define TIMEOUT_URGENCY_LEEWAY 0x20 /* don't ignore provided leeway value */
	172
	173	#define TIMEOUT_URGENCY_FIRST_AVAIL 0x40 /* first available bit outside of urgency mask/leeway */
	174
91447636	175	#ifdef KERNEL_PRIVATE
9bccf70c A	176
9bccf70c A	177	#ifdef MACH_KERNEL_PRIVATE
1c79356b A	178
1c79356b A	179	#include <kern/misc_protos.h>
9bccf70c	180	typedef struct clock *clock_t;
1c79356b	181
91447636 A	182	typedef struct mig_object *mig_object_t;
	183	#define MIG_OBJECT_NULL ((mig_object_t) 0)
	184
	185	typedef struct mig_notify *mig_notify_t;
	186	#define MIG_NOTIFY_NULL ((mig_notify_t) 0)
9bccf70c	187
2d21ac55 A	188	typedef struct pset_node *pset_node_t;
	189	#define PSET_NODE_NULL ((pset_node_t) 0)
	190
	191	typedef struct affinity_set *affinity_set_t;
	192	#define AFFINITY_SET_NULL ((affinity_set_t) 0)
91447636	193
6d2010ae A	194	typedef struct run_queue *run_queue_t;
	195	#define RUN_QUEUE_NULL ((run_queue_t) 0)
	196
	197	typedef struct grrr_run_queue *grrr_run_queue_t;
	198	#define GRRR_RUN_QUEUE_NULL ((grrr_run_queue_t) 0)
	199
	200	typedef struct grrr_group *grrr_group_t;
	201	#define GRRR_GROUP_NULL ((grrr_group_t) 0)
	202
91447636	203	#else /* MACH_KERNEL_PRIVATE */
9bccf70c	204
9bccf70c	205	struct wait_queue_set ;
2d21ac55	206	struct _wait_queue_link ;
91447636 A	207
91447636 A	208	#endif /* MACH_KERNEL_PRIVATE */
9bccf70c A	209
	210	typedef struct wait_queue_set *wait_queue_set_t;
	211	#define WAIT_QUEUE_SET_NULL ((wait_queue_set_t)0)
	212	#define SIZEOF_WAITQUEUE_SET wait_queue_set_size()
	213
2d21ac55	214	typedef struct _wait_queue_link *wait_queue_link_t;
9bccf70c A	215	#define WAIT_QUEUE_LINK_NULL ((wait_queue_link_t)0)
9bccf70c A	216	#define SIZEOF_WAITQUEUE_LINK wait_queue_link_size()
1c79356b	217
9bccf70c A	218	/* legacy definitions - going away */
	219	struct wait_queue_sub ;
	220	typedef struct wait_queue_sub *wait_queue_sub_t;
	221	#define WAIT_QUEUE_SUB_NULL ((wait_queue_sub_t)0)
	222	#define SIZEOF_WAITQUEUE_SUB wait_queue_set_size()
1c79356b	223
91447636	224	#endif /* KERNEL_PRIVATE */
1c79356b A	225
1c79356b A	226	#endif /* _KERN_KERN_TYPES_H_ */