[apple/xnu.git] / bsd / sys / spawn_internal.h

/*
 * Copyright (c) 2006 Apple Computer, 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@
 */


/*
 * [SPN] Support for _POSIX_SPAWN
 *
 * This file contains internal data structures which are externally represented
 * as opaque void pointers to prevent introspection.  This permits us to
 * change the underlying implementation of the code to maintain it or to
 * support new features, as needed, without the consumer needing to recompile
 * their code because of structure size changes or data reorganization.
 */

#ifndef	_SYS_SPAWN_INTERNAL_H_
#define	_SYS_SPAWN_INTERNAL_H_

#include <sys/_types.h>		/* __offsetof(), __darwin_size_t */
#include <sys/syslimits.h>	/* PATH_MAX */
#include <sys/spawn.h>
#include <mach/machine.h>
#include <mach/port.h>
#include <mach/exception_types.h>

/*
 * Allowable posix_spawn() port action types
 */
typedef enum {
	PSPA_SPECIAL = 0,
	PSPA_EXCEPTION = 1,
	PSPA_AU_SESSION = 2,
} pspa_t;

/*
 * Internal representation of one port to be set on posix_spawn().
 * Currently this is limited to setting special and exception ports,
 * but could be extended to other inheritable port types.
 */
typedef struct _ps_port_action {
	pspa_t			port_type;
	exception_mask_t	mask;
	mach_port_name_t	new_port;
	exception_behavior_t	behavior;
	thread_state_flavor_t	flavor;
	int			which;
} _ps_port_action_t;

/*
 * A collection of port actions to take on the newly spawned process.
 */
typedef struct _posix_spawn_port_actions {
	int			pspa_alloc;
	int			pspa_count;
	_ps_port_action_t 	pspa_actions[];
} *_posix_spawn_port_actions_t;

/*
 * Returns size in bytes of a _posix_spawn_port_actions holding x elements.
 */
#define	PS_PORT_ACTIONS_SIZE(x)	\
	__offsetof(struct _posix_spawn_port_actions, pspa_actions[(x)])

#define NBINPREFS	4

/*
 * A posix_spawnattr structure contains all of the attribute elements that
 * can be set, as well as any metadata whose validity is signalled by the
 * presence of a bit in the flags field.  All fields are initialized to the
 * appropriate default values by posix_spawnattr_init().
 */
typedef struct _posix_spawnattr {
	short		psa_flags;		/* spawn attribute flags */
	sigset_t	psa_sigdefault;		/* signal set to default */
	sigset_t	psa_sigmask;		/* signal set to mask */
	pid_t		psa_pgroup;		/* pgroup to spawn into */
	cpu_type_t	psa_binprefs[NBINPREFS];   /* cpu affinity prefs*/
	int		psa_pcontrol;		/* process control bits on resource starvation */
	int		psa_apptype;		/* app type and process spec behav */
	uint64_t 	psa_cpumonitor_percent; /* CPU usage monitor percentage */
	uint64_t 	psa_cpumonitor_interval; /* CPU usage monitor interval, in seconds */
	_posix_spawn_port_actions_t	psa_ports; /* special/exception ports */
	/* XXX - k64/u32 unaligned below here */
#if CONFIG_MEMORYSTATUS || CONFIG_EMBEDDED || TARGET_OS_EMBEDDED
	/* Jetsam related */
	short       psa_jetsam_flags; /* flags */
	int         psa_priority;   /* relative importance */
	int         psa_high_water_mark; /* resident page count limit */
#endif
} *_posix_spawnattr_t;

/*
 * Jetsam flags
 */
#if CONFIG_MEMORYSTATUS || CONFIG_EMBEDDED || TARGET_OS_EMBEDDED
#define	POSIX_SPAWN_JETSAM_USE_EFFECTIVE_PRIORITY	0x1
#endif

/*
 * DEPRECATED: maintained for transition purposes only
 * posix_spawn apptype settings.
 */
#if TARGET_OS_EMBEDDED || CONFIG_EMBEDDED
/* for compat sake */
#define POSIX_SPAWN_OSX_TALAPP_START    0x0400
#define POSIX_SPAWN_IOS_RESV1_APP_START 0x0400
#define POSIX_SPAWN_IOS_APPLE_DAEMON_START      0x0800          /* not a bug, same as widget just rename */
#define POSIX_SPAWN_IOS_APP_START       0x1000
#else /* TARGET_OS_EMBEDDED */
#define POSIX_SPAWN_OSX_TALAPP_START    0x0400
#define POSIX_SPAWN_OSX_WIDGET_START    0x0800
#define POSIX_SPAWN_OSX_DBCLIENT_START  0x0800          /* not a bug, same as widget just rename */
#define POSIX_SPAWN_OSX_RESVAPP_START   0x1000          /* reserved for app start usages */
#endif /* TARGET_OS_EMBEDDED */


/*
 * posix_spawn apptype and process attribute settings.
 */
#if TARGET_OS_EMBEDDED || CONFIG_EMBEDDED
#define POSIX_SPAWN_APPTYPE_IOS_APPLEDAEMON    0x0001          /* it is an iOS apple daemon  */
#else /* TARGET_OS_EMBEDDED */
#define POSIX_SPAWN_APPTYPE_OSX_TAL	0x0001		/* it is a TAL app */
#define POSIX_SPAWN_APPTYPE_OSX_WIDGET	0x0002		/* it is a widget */
#define POSIX_SPAWN_APPTYPE_DELAYIDLESLEEP   0x10000000	/* Process is marked to delay idle sleep on disk IO */
#endif /* TARGET_OS_EMBEDDED */

/*
 * Allowable posix_spawn() file actions
 */
typedef enum {
	PSFA_OPEN = 0,
	PSFA_CLOSE = 1,
	PSFA_DUP2 = 2,
	PSFA_INHERIT = 3
} psfa_t;


/*
 * A posix_spawn() file action record for a single action
 *
 * Notes:	We carry around the full open arguments for both the open
 *		and the close to permit the use of a single array of action
 *		elements to be associated with a file actions object.
 *
 *		A possible future optimization would be to break this into
 *		a variable sized vector list to save space (i.e. a separate
 *		string area, allocation of least amount of path buffer per
 *		open action, etc.).
 *
 * XXX:		Currently overloading psfao_oflag for PSFA_DUP2
 */
typedef struct _psfa_action {
	psfa_t	psfaa_type;			/* file action type */
	int	psfaa_filedes;			/* fd to operate on */
	struct _psfaa_open {
		int	psfao_oflag;		/* open flags to use */
		mode_t	psfao_mode;		/* mode for open */
		char	psfao_path[PATH_MAX];	/* path to open */
	} psfaa_openargs;
} _psfa_action_t;


/*
 * Internal representation of posix_spawn() file actions structure
 *
 * Notes:	This is implemented as a structure followed by an array of
 *		file action records.  The psfa_act_alloc value is the number
 *		of elements allocated in this array, and the psfa_act_count is
 *		the number of elements currently in use (to permit some form
 *		of preallocation, e.g. a power of 2 growth for reallocation,
 *		etc.).
 *
 *		A possible future optimization would keep a size value and
 *		a structure base reference pointer to permit copyin to the
 *		kernel directly as a single blob, without damaging relative
 *		internal pointer math.  It's probably better that this be a
 *		long long rather than a true pointer, to make it invariant
 *		for 32 vs. 64 bt programming SPIs.
 */
typedef struct _posix_spawn_file_actions {
	int		psfa_act_alloc;		/* available actions space */
	int		psfa_act_count;		/* count of defined actions */
	_psfa_action_t	psfa_act_acts[];	/* actions array (uses c99) */
} *_posix_spawn_file_actions_t;

/*
 * Calculate the size of a structure, given the number of elements that it is
 * capable of containing.
 */
#define	PSF_ACTIONS_SIZE(x)	\
	__offsetof(struct _posix_spawn_file_actions, psfa_act_acts[(x)])

/*
 * Initial count of actions in a struct _posix_spawn_file_actions after it is
 * first allocated; this should be non-zero, since we expect that one would not
 * have been allocated unless there was an intent to use it.
 */
#define	PSF_ACTIONS_INIT_COUNT	2

/*
 * Structure defining the true third argument to the posix_spawn() system call
 * entry point; we wrap it and pass a descriptor so that we can know the
 * copyin size ahead of time, and deal with copying in variant lists of things
 * as single monolithic units, instead of many individual elements.  This is a
 * performance optimization.
 */
struct _posix_spawn_args_desc {
	__darwin_size_t		attr_size;	/* size of attributes block */
	_posix_spawnattr_t	attrp;		/* pointer to block */
	__darwin_size_t	file_actions_size;	/* size of file actions block */
	_posix_spawn_file_actions_t
				file_actions;	/* pointer to block */
	__darwin_size_t	port_actions_size; 	/* size of port actions block */
	_posix_spawn_port_actions_t
				port_actions; 	/* pointer to port block */
};

#ifdef KERNEL
#include <sys/appleapiopts.h>
#ifdef __APPLE_API_PRIVATE

#if __DARWIN_ALIGN_NATURAL
#pragma options align=natural
#endif

struct user32__posix_spawn_args_desc {
	uint32_t		attr_size;	/* size of attributes block */
	uint32_t		attrp;		/* pointer to block */
	uint32_t	file_actions_size;	/* size of file actions block */
	uint32_t		file_actions;	/* pointer to block */
	uint32_t	port_actions_size;	/* size of port actions block */
	uint32_t		port_actions;	/* pointer to block */
};

struct user__posix_spawn_args_desc {
	user_size_t		attr_size;	/* size of attributes block */
	user_addr_t		attrp;		/* pointer to block */
	user_size_t	file_actions_size;	/* size of file actions block */
	user_addr_t		file_actions;	/* pointer to block */
	user_size_t	port_actions_size;	/* size of port actions block */
	user_addr_t		port_actions;	/* pointer to block */
};


#if __DARWIN_ALIGN_NATURAL
#pragma options align=reset
#endif

#endif	/* __APPLE_API_PRIVATE */
#endif	/* KERNEL */
	
#endif	/* _SYS_SPAWN_INTERNAL_H_ */
Commit	Line	Data
2d21ac55 A	1	/*
	2	* Copyright (c) 2006 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
	5	*
	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. The rights granted to you under the License
	10	* may not be used to create, or enable the creation or redistribution of,
	11	* unlawful or unlicensed copies of an Apple operating system, or to
	12	* circumvent, violate, or enable the circumvention or violation of, any
	13	* terms of an Apple operating system software license agreement.
	14	*
	15	* Please obtain a copy of the License at
	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
	17	*
	18	* The Original Code and all software distributed under the License are
	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	22	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	* Please see the License for the specific language governing rights and
	24	* limitations under the License.
	25	*
	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
	27	*/
	28
	29
	30	/*
	31	* [SPN] Support for _POSIX_SPAWN
	32	*
6d2010ae	33	* This file contains internal data structures which are externally represented
2d21ac55 A	34	* as opaque void pointers to prevent introspection. This permits us to
	35	* change the underlying implementation of the code to maintain it or to
	36	* support new features, as needed, without the consumer needing to recompile
	37	* their code because of structure size changes or data reorganization.
	38	*/
	39
	40	#ifndef _SYS_SPAWN_INTERNAL_H_
316670eb	41	#define _SYS_SPAWN_INTERNAL_H_
2d21ac55 A	42
	43	#include <sys/_types.h> /* __offsetof(), __darwin_size_t */
	44	#include <sys/syslimits.h> /* PATH_MAX */
	45	#include <sys/spawn.h>
	46	#include <mach/machine.h>
	47	#include <mach/port.h>
	48	#include <mach/exception_types.h>
	49
	50	/*
	51	* Allowable posix_spawn() port action types
	52	*/
	53	typedef enum {
	54	PSPA_SPECIAL = 0,
	55	PSPA_EXCEPTION = 1,
b0d623f7	56	PSPA_AU_SESSION = 2,
2d21ac55 A	57	} pspa_t;
	58
	59	/*
	60	* Internal representation of one port to be set on posix_spawn().
	61	* Currently this is limited to setting special and exception ports,
	62	* but could be extended to other inheritable port types.
	63	*/
	64	typedef struct _ps_port_action {
	65	pspa_t port_type;
	66	exception_mask_t mask;
316670eb	67	mach_port_name_t new_port;
2d21ac55 A	68	exception_behavior_t behavior;
	69	thread_state_flavor_t flavor;
	70	int which;
	71	} _ps_port_action_t;
	72
	73	/*
	74	* A collection of port actions to take on the newly spawned process.
	75	*/
	76	typedef struct _posix_spawn_port_actions {
	77	int pspa_alloc;
	78	int pspa_count;
	79	_ps_port_action_t pspa_actions[];
	80	} *_posix_spawn_port_actions_t;
	81
	82	/*
	83	* Returns size in bytes of a _posix_spawn_port_actions holding x elements.
	84	*/
	85	#define PS_PORT_ACTIONS_SIZE(x) \
	86	__offsetof(struct _posix_spawn_port_actions, pspa_actions[(x)])
	87
	88	#define NBINPREFS 4
	89
	90	/*
	91	* A posix_spawnattr structure contains all of the attribute elements that
	92	* can be set, as well as any metadata whose validity is signalled by the
	93	* presence of a bit in the flags field. All fields are initialized to the
	94	* appropriate default values by posix_spawnattr_init().
	95	*/
	96	typedef struct _posix_spawnattr {
	97	short psa_flags; /* spawn attribute flags */
	98	sigset_t psa_sigdefault; /* signal set to default */
	99	sigset_t psa_sigmask; /* signal set to mask */
	100	pid_t psa_pgroup; /* pgroup to spawn into */
	101	cpu_type_t psa_binprefs[NBINPREFS]; /* cpu affinity prefs*/
b0d623f7	102	int psa_pcontrol; /* process control bits on resource starvation */
316670eb A	103	int psa_apptype; /* app type and process spec behav */
	104	uint64_t psa_cpumonitor_percent; /* CPU usage monitor percentage */
	105	uint64_t psa_cpumonitor_interval; /* CPU usage monitor interval, in seconds */
	106	_posix_spawn_port_actions_t psa_ports; /* special/exception ports */
	107	/* XXX - k64/u32 unaligned below here */
	108	#if CONFIG_MEMORYSTATUS \|\| CONFIG_EMBEDDED \|\| TARGET_OS_EMBEDDED
	109	/* Jetsam related */
	110	short psa_jetsam_flags; /* flags */
	111	int psa_priority; /* relative importance */
	112	int psa_high_water_mark; /* resident page count limit */
	113	#endif
2d21ac55 A	114	} *_posix_spawnattr_t;
2d21ac55 A	115
316670eb A	116	/*
	117	* Jetsam flags
	118	*/
	119	#if CONFIG_MEMORYSTATUS \|\| CONFIG_EMBEDDED \|\| TARGET_OS_EMBEDDED
	120	#define POSIX_SPAWN_JETSAM_USE_EFFECTIVE_PRIORITY 0x1
	121	#endif
	122
	123	/*
	124	* DEPRECATED: maintained for transition purposes only
	125	* posix_spawn apptype settings.
	126	*/
	127	#if TARGET_OS_EMBEDDED \|\| CONFIG_EMBEDDED
	128	/* for compat sake */
	129	#define POSIX_SPAWN_OSX_TALAPP_START 0x0400
	130	#define POSIX_SPAWN_IOS_RESV1_APP_START 0x0400
	131	#define POSIX_SPAWN_IOS_APPLE_DAEMON_START 0x0800 /* not a bug, same as widget just rename */
	132	#define POSIX_SPAWN_IOS_APP_START 0x1000
	133	#else /* TARGET_OS_EMBEDDED */
	134	#define POSIX_SPAWN_OSX_TALAPP_START 0x0400
	135	#define POSIX_SPAWN_OSX_WIDGET_START 0x0800
	136	#define POSIX_SPAWN_OSX_DBCLIENT_START 0x0800 /* not a bug, same as widget just rename */
	137	#define POSIX_SPAWN_OSX_RESVAPP_START 0x1000 /* reserved for app start usages */
	138	#endif /* TARGET_OS_EMBEDDED */
	139
	140
	141	/*
	142	* posix_spawn apptype and process attribute settings.
	143	*/
	144	#if TARGET_OS_EMBEDDED \|\| CONFIG_EMBEDDED
	145	#define POSIX_SPAWN_APPTYPE_IOS_APPLEDAEMON 0x0001 /* it is an iOS apple daemon */
	146	#else /* TARGET_OS_EMBEDDED */
	147	#define POSIX_SPAWN_APPTYPE_OSX_TAL 0x0001 /* it is a TAL app */
	148	#define POSIX_SPAWN_APPTYPE_OSX_WIDGET 0x0002 /* it is a widget */
	149	#define POSIX_SPAWN_APPTYPE_DELAYIDLESLEEP 0x10000000 /* Process is marked to delay idle sleep on disk IO */
	150	#endif /* TARGET_OS_EMBEDDED */
2d21ac55 A	151
	152	/*
	153	* Allowable posix_spawn() file actions
	154	*/
	155	typedef enum {
	156	PSFA_OPEN = 0,
	157	PSFA_CLOSE = 1,
6d2010ae A	158	PSFA_DUP2 = 2,
6d2010ae A	159	PSFA_INHERIT = 3
2d21ac55 A	160	} psfa_t;
	161
	162
	163	/*
	164	* A posix_spawn() file action record for a single action
	165	*
	166	* Notes: We carry around the full open arguments for both the open
	167	* and the close to permit the use of a single array of action
	168	* elements to be associated with a file actions object.
	169	*
	170	* A possible future optimization would be to break this into
	171	* a variable sized vector list to save space (i.e. a separate
	172	* string area, allocation of least amount of path buffer per
	173	* open action, etc.).
	174	*
	175	* XXX: Currently overloading psfao_oflag for PSFA_DUP2
	176	*/
	177	typedef struct _psfa_action {
	178	psfa_t psfaa_type; /* file action type */
	179	int psfaa_filedes; /* fd to operate on */
	180	struct _psfaa_open {
	181	int psfao_oflag; /* open flags to use */
	182	mode_t psfao_mode; /* mode for open */
	183	char psfao_path[PATH_MAX]; /* path to open */
	184	} psfaa_openargs;
	185	} _psfa_action_t;
	186
	187
	188	/*
	189	* Internal representation of posix_spawn() file actions structure
	190	*
	191	* Notes: This is implemented as a structure followed by an array of
	192	* file action records. The psfa_act_alloc value is the number
	193	* of elements allocated in this array, and the psfa_act_count is
	194	* the number of elements currently in use (to permit some form
	195	* of preallocation, e.g. a power of 2 growth for reallocation,
	196	* etc.).
	197	*
	198	* A possible future optimization would keep a size value and
	199	* a structure base reference pointer to permit copyin to the
	200	* kernel directly as a single blob, without damaging relative
	201	* internal pointer math. It's probably better that this be a
	202	* long long rather than a true pointer, to make it invariant
	203	* for 32 vs. 64 bt programming SPIs.
	204	*/
	205	typedef struct _posix_spawn_file_actions {
	206	int psfa_act_alloc; /* available actions space */
	207	int psfa_act_count; /* count of defined actions */
	208	_psfa_action_t psfa_act_acts[]; /* actions array (uses c99) */
	209	} *_posix_spawn_file_actions_t;
	210
	211	/*
	212	* Calculate the size of a structure, given the number of elements that it is
	213	* capable of containing.
	214	*/
	215	#define PSF_ACTIONS_SIZE(x) \
	216	__offsetof(struct _posix_spawn_file_actions, psfa_act_acts[(x)])
	217
	218	/*
	219	* Initial count of actions in a struct _posix_spawn_file_actions after it is
	220	* first allocated; this should be non-zero, since we expect that one would not
	221	* have been allocated unless there was an intent to use it.
	222	*/
	223	#define PSF_ACTIONS_INIT_COUNT 2
224
225	/*
226	* Structure defining the true third argument to the posix_spawn() system call
227	* entry point; we wrap it and pass a descriptor so that we can know the
228	* copyin size ahead of time, and deal with copying in variant lists of things
229	* as single monolithic units, instead of many individual elements. This is a
230	* performance optimization.
231	*/
232	struct _posix_spawn_args_desc {
233	__darwin_size_t attr_size; /* size of attributes block */
234	_posix_spawnattr_t attrp; /* pointer to block */
235	__darwin_size_t file_actions_size; /* size of file actions block */
236	_posix_spawn_file_actions_t
237	file_actions; /* pointer to block */
316670eb	238	__darwin_size_t port_actions_size; /* size of port actions block */
2d21ac55 A	239	_posix_spawn_port_actions_t
	240	port_actions; /* pointer to port block */
	241	};
	242
	243	#ifdef KERNEL
	244	#include <sys/appleapiopts.h>
	245	#ifdef __APPLE_API_PRIVATE
	246
	247	#if __DARWIN_ALIGN_NATURAL
	248	#pragma options align=natural
	249	#endif
	250
b0d623f7 A	251	struct user32__posix_spawn_args_desc {
	252	uint32_t attr_size; /* size of attributes block */
	253	uint32_t attrp; /* pointer to block */
	254	uint32_t file_actions_size; /* size of file actions block */
	255	uint32_t file_actions; /* pointer to block */
	256	uint32_t port_actions_size; /* size of port actions block */
	257	uint32_t port_actions; /* pointer to block */
	258	};
	259
2d21ac55 A	260	struct user__posix_spawn_args_desc {
	261	user_size_t attr_size; /* size of attributes block */
	262	user_addr_t attrp; /* pointer to block */
	263	user_size_t file_actions_size; /* size of file actions block */
	264	user_addr_t file_actions; /* pointer to block */
	265	user_size_t port_actions_size; /* size of port actions block */
	266	user_addr_t port_actions; /* pointer to block */
	267	};
	268
	269
	270	#if __DARWIN_ALIGN_NATURAL
	271	#pragma options align=reset
	272	#endif
	273
	274	#endif /* __APPLE_API_PRIVATE */
	275	#endif /* KERNEL */
	276
	277	#endif /* _SYS_SPAWN_INTERNAL_H_ */