xnu-3789.31.2.tar.gz

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

/*
 * Copyright (c) 2013 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@
 */

#ifndef _SYS_COALITION_H_
#define _SYS_COALITION_H_

#include <stdint.h>
#include <sys/cdefs.h>
#include <sys/types.h>

#include <mach/coalition.h>

__BEGIN_DECLS

#ifndef KERNEL
/* Userspace syscall prototypes */

/* Syscalls */
int coalition_create(uint64_t *cid_out, uint32_t flags);
int coalition_terminate(uint64_t cid, uint32_t flags);
int coalition_reap(uint64_t cid, uint32_t flags);

/* Wrappers around __coalition_info syscall (with proper struct types) */
int coalition_info_resource_usage(uint64_t cid, struct coalition_resource_usage *cru, size_t sz);

#else /* KERNEL */

#if CONFIG_COALITIONS
/* in-kernel BSD interfaces */

/*
 * coalition_id:
 * Get the unique 64-bit identifier associated with the given coalition
 */
uint64_t coalition_id(coalition_t coal);


/*
 * coalitions_get_list:
 * Get a list of coalitions as procinfo_coalinfo structures
 *
 * This interface is primarily to support libproc.
 *
 * Parameters:
 * 	type      : The COALITION_TYPE of the coalitions to investigate.
 * 	            Valid types can be found in <mach/coalition.h>
 * 	coal_list : Pointer to an array of procinfo_coalinfo structures
 * 	            that will be filled with information about each
 * 	            coalition whose type matches 'type'
 * 	            NOTE: This can be NULL to perform a simple query of
 * 	            the total number of coalitions.
 * 	list_sz   : The size (in number of structures) of 'coal_list'
 *
 * Returns: 0 if no coalitions matching 'type' are found
 *          Otherwise: the number of coalitions whose type matches
 *                     the 'type' parameter (all coalitions if type == -1)
 */
extern int coalitions_get_list(int type, struct procinfo_coalinfo *coal_list, int list_sz);


/*
 * coalition_is_leader:
 * Determine if a task is a coalition leader.
 *
 * Parameters:
 * 	task      : The task to investigate
 * 	coal_type : The COALITION_TYPE of the coalition to investigate.
 * 	            Valid types can be found in <mach/coalition.h>
 * 	coal      : If 'task' is a valid task, and is a member of a coalition
 * 	            of type 'coal_type', then 'coal' will be filled in with
 * 	            the corresponding coalition_t object.
 * 	            NOTE: This will be filled in whether or not the 'task' is
 * 	                  a leader in the coalition. However, if 'task' is
 * 	                  not a member of a coalition of type 'coal_type' then
 * 	                  'coal' will be filled in with COALITION_NULL.
 * 	            NOTE: This can be NULL
 *
 * Returns: TRUE if 'task' is a coalition leader, FALSE otherwise.
 */
extern boolean_t coalition_is_leader(task_t task, int coal_type, coalition_t *coal);

/*
 * coalition_get_leader:
 * Get a task reference on the leader of a given coalition
 *
 * Parameters:
 *	coal      : The coalition to investigate
 *
 * Returns: A referenced task pointer of the leader of the given coalition.
 *          This could be TASK_NULL if the coalition doesn't have a leader.
 *          If the return value is non-null, the caller is responsible to call
 *          task_deallocate on the returned value.
 */
extern task_t coalition_get_leader(coalition_t coal);


/*
 * coalition_get_task_count:
 * Sum up the number of tasks in the given coalition
 *
 * Parameters:
 * 	coal     : The coalition to investigate
 *
 * Returns: The number of tasks in the coalition
 */
extern int coalition_get_task_count(coalition_t coal);

/*
 * coalition_get_page_count:
 * Sum up the page count for each task in the coalition specified by 'coal'
 *
 * Parameters:
 * 	coal     : The coalition to investigate
 * 	ntasks   : If non-NULL, this will be filled in with the number of
 * 	           tasks in the coalition.
 *
 * Returns: The sum of all pages used by all members of the coalition
 */
extern uint64_t coalition_get_page_count(coalition_t coal, int *ntasks);

/*
 * coalition_get_pid_list:
 * Gather a list of constituent PIDs of tasks within a coalition playing a
 * given role.
 *
 * Parameters:
 * 	coal       : The coalition to investigate
 * 	rolemask   : The set of coalition task roles used to filter the list
 * 	             of PIDs returned in 'pid_list'. Roles can be combined
 * 	             using the COALITION_ROLEMASK_* tokens found in
 * 	             <mach/coalition.h>. Each PID returned is guaranteed to
 * 	             be tagged with one of the task roles specified by this
 * 	             mask.
 * 	sort_order : The order in which the returned PIDs should be sorted
 * 	             by default this is in descending page count.
 * 	pid_list   : Pointer to an array of PIDs that will be filled with
 * 	             members of the coalition tagged with the given 'taskrole'
 * 	list_sz    : The size (in number of PIDs) of 'pid_list'
 *
 * Note:
 * This function will return the list of PIDs in a sorted order. By default
 * the PIDs will be sorted by task page count in descending order. In the
 * future it may be possible for user space to specify a level of importance
 * for each coalition member. If there is a user space specified importance,
 * then the list of PIDs returned will be sorted in _ascending_ importance,
 * i.e., pid_list[0] will be the least important task (or the largest consumer
 * of memory). The desired sort order can be specified using the
 * COALITION_SORT_* definitions in osfmk/mach/coalition.h
 *
 * It is also possible to return an unsorted list of PIDs using the special
 * sort type 'COALITION_SORT_NOSORT'
 *
 * Returns: < 0 on ERROR
 *          0 if 'coal' contains no tasks whose role is 'taskrole'
 *              (or if the coalition is being deallocated)
 *          Otherwise: the number of PIDs in the coalition whose role is
 *                     'taskrole'. NOTE: This may be larger or smaller than
 *                     the 'pid_list' array.
 *
 */
extern int coalition_get_pid_list(coalition_t coal, uint32_t rolemask,
				  int sort_order, int *pid_list, int list_sz);

#else /* !CONFIG_COALITIONS */
static inline uint64_t coalition_id(__unused coalition_t coal)
{
	return 0;
}

static inline int coalitions_get_list(__unused int type,
				      __unused struct procinfo_coalinfo *coal_list,
				      __unused int list_sz)
{
	return 0;
}

static inline boolean_t coalition_is_leader(__unused task_t task,
					    __unused int coal_type,
					    coalition_t *coal)
{
	*coal = COALITION_NULL;
	return FALSE;
}

static inline int coalition_get_task_count(__unused coalition_t coal)
{
	return 0;
}

static inline uint64_t coalition_get_page_count(__unused coalition_t coal,
						__unused int *ntasks)
{
	return 0;
}

static inline int coalition_get_pid_list(__unused coalition_t coal,
					 __unused uint32_t rolemask,
					 __unused int sort_order,
					 __unused int *pid_list,
					 __unused int list_sz)
{
	return 0;
}
#endif

#endif /* KERNEL */

__END_DECLS

#endif /* _SYS_COALITION_H_ */