9. Processors and Processor Sets

This section describes the Mach interface to processor sets and individual processors. The interface allows to group processors into sets and control the processors and processor sets.

A processor is not a central part of the interface. It is mostly of relevance as a part of a processor set. Threads are always assigned to processor sets, and all processors in a set are equally involved in executing all threads assigned to that set.

The processor set is represented by two ports, a name port processor_set_name used to query information about the host accessible to everyone, and a control port processor_set used to manipulate it.

9.1 Processor Set Interface

9.1.1 Processor Set Ports

Data type: processor_set_name_t

This is a mach_port_t and used to hold the port name of a processor set name port that names the processor set. Any task can get a send right to name port of a processor set. The processor set name port allows to get information about the processor set.

Data type: processor_set_t

This is a mach_port_t and used to hold the port name of a privileged processor set control port that represents the processor set. Operations on the processor set are implemented as remote procedure calls to the processor set port. The processor set port allows to manipulate the processor set.

9.1.2 Processor Set Access

Function: kern_return_t host_processor_sets (host_t host, processor_set_name_array_t *processor_sets, mach_msg_type_number_t *processor_sets_count)

The function host_processor_sets gets send rights to the name port for each processor set currently assigned to host.

host_processor_set_priv can be used to obtain the control ports from these if desired. processor_sets is an array that is created as a result of this call. The caller may wish to vm_deallocate this array when the data is no longer needed. processor_sets_count is set to the number of processor sets in the processor_sets.

This function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if host is not a host.

Function: kern_return_t host_processor_set_priv (host_priv_t host_priv, processor_set_name_t set_name, processor_set_t *set)

The function host_processor_set_priv allows a privileged application to obtain the control port set for an existing processor set from its name port set_name. The privileged host port host_priv is required.

This function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if host_priv is not a valid host control port.

Function: kern_return_t processor_set_default (host_t host, processor_set_name_t *default_set)

The function processor_set_default returns the default processor set of host in default_set. The default processor set is used by all threads, tasks, and processors that are not explicitly assigned to other sets. processor_set_default returns a port that can be used to obtain information about this set (e.g. how many threads are assigned to it). This port cannot be used to perform operations on that set.

This function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_ARGUMENT if host is not a host and KERN_INVALID_ADDRESS if default_set points to inaccessible memory.

9.1.3 Processor Set Creation

Function: kern_return_t processor_set_create (host_t host, processor_set_t *new_set, processor_set_name_t *new_name)

The function processor_set_create creates a new processor set on host and returns the two ports associated with it. The port returned in new_set is the actual port representing the set. It is used to perform operations such as assigning processors, tasks, or threads. The port returned in new_name identifies the set, and is used to obtain information about the set.

This function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_ARGUMENT if host is not a host, KERN_INVALID_ADDRESS if new_set or new_name points to inaccessible memory and KERN_FAILURE is the operating system does not support processor allocation.

9.1.4 Processor Set Destruction

Function: kern_return_t processor_set_destroy (processor_set_t processor_set)

The function processor_set_destroy destroys the specified processor set. Any assigned processors, tasks, or threads are reassigned to the default set. The object port for the processor set is required (not the name port). The default processor set cannot be destroyed.

This function returns KERN_SUCCESS if the set was destroyed, KERN_FAILURE if an attempt was made to destroy the default processor set, or the operating system does not support processor allocation, and KERN_INVALID_ARGUMENT if processor_set is not a valid processor set control port.

9.1.5 Tasks and Threads on Sets

Function: kern_return_t processor_set_tasks (processor_set_t processor_set, task_array_t *task_list, mach_msg_type_number_t *task_count)

The function processor_set_tasks gets send rights to the kernel port for each task currently assigned to processor_set.

task_list is an array that is created as a result of this call. The caller may wish to vm_deallocate this array when the data is no longer needed. task_count is set to the number of tasks in the task_list.

This function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if processor_set is not a processor set.

Function: kern_return_t processor_set_threads (processor_set_t processor_set, thread_array_t *thread_list, mach_msg_type_number_t *thread_count)

The function processor_set_thread gets send rights to the kernel port for each thread currently assigned to processor_set.

thread_list is an array that is created as a result of this call. The caller may wish to vm_deallocate this array when the data is no longer needed. thread_count is set to the number of threads in the thread_list.

This function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if processor_set is not a processor set.

Function: kern_return_t task_assign (task_t task, processor_set_t processor_set, boolean_t assign_threads)

The function task_assign assigns task the set processor_set. This assignment is for the purposes of determining the initial assignment of newly created threads in task. Any previous assignment of the task is nullified. Existing threads within the task are also reassigned if assign_threads is TRUE. They are not affected if it is FALSE.

This function returns KERN_SUCCESS if the assignment has been performed and KERN_INVALID_ARGUMENT if task is not a task, or processor_set is not a processor set on the same host as task.

Function: kern_return_t task_assign_default (task_t task, boolean_t assign_threads)

The function task_assign_default is a variant of task_assign that assigns the task to the default processor set on that task's host. This variant exists because the control port for the default processor set is privileged and not ususally available to users.

This function returns KERN_SUCCESS if the assignment has been performed and KERN_INVALID_ARGUMENT if task is not a task.

Function: kern_return_t task_get_assignment (task_t task, processor_set_name_t *assigned_set)

The function task_get_assignment returns the name of the processor set to which the thread is currently assigned in assigned_set. This port can only be used to obtain information about the processor set.

This function returns KERN_SUCCESS if the assignment has been performed, KERN_INVALID_ADDRESS if processor_set points to inaccessible memory, and KERN_INVALID_ARGUMENT if task is not a task.

Function: kern_return_t thread_assign (thread_t thread, processor_set_t processor_set)

The function thread_assign assigns thread the set processor_set. After the assignment is completed, the thread only executes on processors assigned to the designated processor set. If there are no such processors, then the thread is unable to execute. Any previous assignment of the thread is nullified. Unix system call compatibility code may temporarily force threads to execute on the master processor.

This function returns KERN_SUCCESS if the assignment has been performed and KERN_INVALID_ARGUMENT if thread is not a thread, or processor_set is not a processor set on the same host as thread.

Function: kern_return_t thread_assign_default (thread_t thread)

The function thread_assign_default is a variant of thread_assign that assigns the thread to the default processor set on that thread's host. This variant exists because the control port for the default processor set is privileged and not ususally available to users.

This function returns KERN_SUCCESS if the assignment has been performed and KERN_INVALID_ARGUMENT if thread is not a thread.

Function: kern_return_t thread_get_assignment (thread_t thread, processor_set_name_t *assigned_set)

The function thread_get_assignment returns the name of the processor set to which the thread is currently assigned in assigned_set. This port can only be used to obtain information about the processor set.

This function returns KERN_SUCCESS if the assignment has been performed, KERN_INVALID_ADDRESS if processor_set points to inaccessible memory, and KERN_INVALID_ARGUMENT if thread is not a thread.

9.1.6 Processor Set Priority

Function: kern_return_t processor_set_max_priority (processor_set_t processor_set, int max_priority, boolean_t change_threads)

The function processor_set_max_priority is used to set the maximum priority for a processor set. The priority of a processor set is used only for newly created threads (thread's maximum priority is set to processor set's) and the assignment of threads to the set (thread's maximum priority is reduced if it exceeds the set's maximum priority, thread's priority is similarly reduced). processor_set_max_priority changes this priority. It also sets the maximum priority of all threads assigned to the processor set to this new priority if change_threads is TRUE. If this maximum priority is less than the priorities of any of these threads, their priorities will also be set to this new value.

This function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if processor_set is not a processor set or priority is not a valid priority.

9.1.7 Processor Set Policy

Function: kern_return_t processor_set_policy_enable (processor_set_t processor_set, int policy)

Function: kern_return_t processor_set_policy_disable (processor_set_t processor_set, int policy, boolean_t change_threads)

Processor sets may restrict the scheduling policies to be used for threads assigned to them. These two calls provide the mechanism for designating permitted and forbidden policies. The current set of permitted policies can be obtained from processor_set_info. Timesharing may not be forbidden by any processor set. This is a compromise to reduce the complexity of the assign operation; any thread whose policy is forbidden by the target processor set has its policy reset to timesharing. If the change_threads argument to processor_set_policy_disable is true, threads currently assigned to this processor set and using the newly disabled policy will have their policy reset to timesharing.

`mach/policy.h' contains the allowed policies; it is included by `mach.h'. Not all policies (e.g. fixed priority) are supported by all systems.

This function returns KERN_SUCCESS if the operation was completed successfully and KERN_INVALID_ARGUMENT if processor_set is not a processor set or policy is not a valid policy, or an attempt was made to disable timesharing.

9.1.8 Processor Set Info

Function: kern_return_t processor_set_info (processor_set_name_t set_name, int flavor, host_t *host, processor_set_info_t processor_set_info, mach_msg_type_number_t *processor_set_info_count)

The function processor_set_info returns the selected information array for a processor set, as specified by flavor.

host is set to the host on which the processor set resides. This is the non-privileged host port.

processor_set_info is an array of integers that is supplied by the caller and returned filled with specified information. processor_set_info_count is supplied as the maximum number of integers in processor_set_info. On return, it contains the actual number of integers in processor_set_info. The maximum number of integers returned by any flavor is PROCESSOR_SET_INFO_MAX.

The type of information returned is defined by flavor, which can be one of the following:

PROCESSOR_SET_BASIC_INFO

The function returns basic information about the processor set, as defined by processor_set_basic_info_t. This includes the number of tasks and threads assigned to the processor set. The number of integers returned is PROCESSOR_SET_BASIC_INFO_COUNT.

PROCESSOR_SET_SCHED_INFO

The function returns information about the schduling policy for the processor set as defined by processor_set_sched_info_t. The number of integers returned is PROCESSOR_SET_SCHED_INFO_COUNT.

Some machines may define additional (machine-dependent) flavors.

The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if processor_set is not a processor set or flavor is not recognized. The function returns MIG_ARRAY_TOO_LARGE if the returned info array is too large for processor_set_info. In this case, processor_set_info is filled as much as possible and processor_set_info_count is set to the number of elements that would have been returned if there were enough room.

Data type: struct processor_set_basic_info

This structure is returned in processor_set_info by the processor_set_info function and provides basic information about the processor set. You can cast a variable of type processor_set_info_t to a pointer of this type if you provided it as the processor_set_info parameter for the PROCESSOR_SET_BASIC_INFO flavor of processor_set_info. It has the following members:

int processor_count

number of processors

int task_count

number of tasks

int thread_count

number of threads

int load_average

scaled load average

int mach_factor

scaled mach factor

Data type: processor_set_basic_info_t

This is a pointer to a struct processor_set_basic_info.

Data type: struct processor_set_sched_info

This structure is returned in processor_set_info by the processor_set_info function and provides schedule information about the processor set. You can cast a variable of type processor_set_info_t to a pointer of this type if you provided it as the processor_set_info parameter for the PROCESSOR_SET_SCHED_INFO flavor of processor_set_info. It has the following members:

int policies

allowed policies

int max_priority

max priority for new threads

Data type: processor_set_sched_info_t

This is a pointer to a struct processor_set_sched_info.

9.2 Processor Interface

Data type: processor_t

This is a mach_port_t and used to hold the port name of a processor port that represents the processor. Operations on the processor are implemented as remote procedure calls to the processor port.

9.2.1 Hosted Processors

Function: kern_return_t host_processors (host_priv_t host_priv, processor_array_t *processor_list, mach_msg_type_number_t *processor_count)

The function host_processors gets send rights to the processor port for each processor existing on host_priv. This is the privileged port that allows its holder to control a processor.

processor_list is an array that is created as a result of this call. The caller may wish to vm_deallocate this array when the data is no longer needed. processor_count is set to the number of processors in the processor_list.

This function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_ARGUMENT if host_priv is not a privileged host port, and KERN_INVALID_ADDRESS if processor_count points to inaccessible memory.

9.2.2 Processor Control

Function: kern_return_t processor_start (processor_t processor)

Function: kern_return_t processor_exit (processor_t processor)

Function: kern_return_t processor_control (processor_t processor, processor_info_t *cmd, mach_msg_type_number_t count)

Some multiprocessors may allow privileged software to control processors. The processor_start, processor_exit, and processor_control operations implement this. The interpretation of the command in cmd is machine dependent. A newly started processor is assigned to the default processor set. An exited processor is removed from the processor set to which it was assigned and ceases to be active.

count contains the length of the command cmd as a number of ints.

Availability limited. All of these operations are machine-dependent. They may do nothing. The ability to restart an exited processor is also machine-dependent.

This function returns KERN_SUCCESS if the operation was performed, KERN_FAILURE if the operation was not performed (a likely reason is that it is not supported on this processor), KERN_INVALID_ARGUMENT if processor is not a processor, and KERN_INVALID_ADDRESS if cmd points to inaccessible memory.

9.2.3 Processors and Sets

Function: kern_return_t processor_assign (processor_t processor, processor_set_t processor_set, boolean_t wait)

The function processor_assign assigns processor to the the set processor_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 reassigned. All processors take clock interrupts at all times. 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 faster, especially if the kernel has more than one dedicated internal thread for processor assignment. Redirection of other device interrupts away from processors assigned to other than the default processor set is machine-dependent. Intermediaries that interpose on ports must be sure to interpose on both ports involved in this call if they interpose on either.

This function returns KERN_SUCCESS if the assignment has been performed, KERN_INVALID_ARGUMENT if processor is not a processor, or processor_set is not a processor set on the same host as processor.

Function: kern_return_t processor_get_assignment (processor_t processor, processor_set_name_t *assigned_set)

The function processor_get_assignment obtains the current assignment of a processor. The name port of the processor set is returned in assigned_set.

9.2.4 Processor Info

Function: kern_return_t processor_info (processor_t processor, int flavor, host_t *host, processor_info_t processor_info, mach_msg_type_number_t *processor_info_count)

The function processor_info returns the selected information array for a processor, as specified by flavor.

host is set to the host on which the processor set resides. This is the non-privileged host port.

processor_info is an array of integers that is supplied by the caller and returned filled with specified information. processor_info_count is supplied as the maximum number of integers in processor_info. On return, it contains the actual number of integers in processor_info. The maximum number of integers returned by any flavor is PROCESSOR_INFO_MAX.

The type of information returned is defined by flavor, which can be one of the following:

PROCESSOR_BASIC_INFO

The function returns basic information about the processor, as defined by processor_basic_info_t. This includes the slot number of the processor. The number of integers returned is PROCESSOR_BASIC_INFO_COUNT.

Machines which require more configuration information beyond the slot number are expected to define additional (machine-dependent) flavors.

The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if processor is not a processor or flavor is not recognized. The function returns MIG_ARRAY_TOO_LARGE if the returned info array is too large for processor_info. In this case, processor_info is filled as much as possible and processor_infoCnt is set to the number of elements that would have been returned if there were enough room.

Data type: struct processor_basic_info

This structure is returned in processor_info by the processor_info function and provides basic information about the processor. You can cast a variable of type processor_info_t to a pointer of this type if you provided it as the processor_info parameter for the PROCESSOR_BASIC_INFO flavor of processor_info. It has the following members:

cpu_type_t cpu_type

cpu type

cpu_subtype_t cpu_subtype

cpu subtype

boolean_t running

is processor running?

int slot_num

slot number

boolean_t is_master

is this the master processor

Data type: processor_basic_info_t

This is a pointer to a struct processor_basic_info.