8. Host Interface

This section describes the Mach interface to a host executing a Mach kernel. The interface allows to query statistics about a host and control its behaviour.

A host is represented by two ports, a name port host used to query information about the host accessible to everyone, and a control port host_priv used to manipulate it. For example, you can query the current time using the name port, but to change the time you need to send a message to the host control port.

Everything described in this section is declared in the header file `mach.h'.

8.1 Host Ports

Data type: host_t

This is a mach_port_t and used to hold the port name of a host name port (or short: host port). Any task can get a send right to the name port of the host running the task using the mach_host_self system call. The name port can be used query information about the host, for example the current time.

Function: host_t mach_host_self ()

The mach_host_self system call returns the calling thread's host name port. It has an effect equivalent to receiving a send right for the host port. mach_host_self returns the name of the send right. In particular, successive calls will increase the calling task's user-reference count for the send right.

As a special exception, the kernel will overrun the user reference count of the host name port, so that this function can not fail for that reason. Because of this, the user should not deallocate the port right if an overrun might have happened. Otherwise the reference count could drop to zero and the send right be destroyed while the user still expects to be able to use it. As the kernel does not make use of the number of extant send rights anyway, this is safe to do (the host port itself is never destroyed).

The function returns MACH_PORT_NULL if a resource shortage prevented the reception of the send right.

This function is also available in `mach/mach_traps.h'.

Data type: host_priv_t

This is a mach_port_t and used to hold the port name of a privileged host control port. A send right to the host control port is inserted into the first task at bootstrap (see section 3.2 Modules). This is the only way to get access to the host control port in Mach, so the initial task has to preserve the send right carefully, moving a copy of it to other privileged tasks if necessary and denying access to unprivileged tasks.

8.2 Host Information

Function: kern_return_t host_info (host_t host, int flavor, host_info_t host_info, mach_msg_type_number_t *host_info_count)

The host_info function returns various information about host. host_info is an array of integers that is supplied by the caller. It will be filled with the requested information. host_info_count is supplied as the maximum number of integers in host_info. On return, it contains the actual number of integers in host_info. The maximum number of integers returned by any flavor is HOST_INFO_MAX.

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

HOST_BASIC_INFO

The function returns basic information about the host, as defined by host_basic_info_t. This includes the number of processors, their type, and the amount of memory installed in the system. The number of integers returned is HOST_BASIC_INFO_COUNT. For how to get more information about the processor, see 9.2 Processor Interface.

HOST_PROCESSOR_SLOTS

The function returns the numbers of the slots with active processors in them. The number of integers returned can be up to max_cpus, as returned by the HOST_BASIC_INFO flavor of host_info.

HOST_SCHED_INFO

The function returns information of interest to schedulers as defined by host_sched_info_t. The number of integers returned is HOST_SCHED_INFO_COUNT.

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

Data type: struct host_basic_info

A pointer to this structure is returned in host_info by the host_info function and provides basic information about the host. You can cast a variable of type host_info_t to a pointer of this type if you provided it as the host_info parameter for the HOST_BASIC_INFO flavor of host_info. It has the following members:

int max_cpus

The maximum number of possible processors for which the kernel is configured.

int avail_cpus

The number of cpus currently available.

vm_size_t memory_size

The size of physical memory in bytes.

cpu_type_t cpu_type

The type of the master processor.

cpu_subtype_t cpu_subtype

The subtype of the master processor.

The type and subtype of the individual processors are also available by processor_info, see 9.2 Processor Interface.

Data type: host_basic_info_t

This is a pointer to a struct host_basic_info.

Data type: struct host_sched_info

A pointer to this structure is returned in host_info by the host_info function and provides information of interest to schedulers. You can cast a variable of type host_info_t to a pointer of this type if you provided it as the host_info parameter for the HOST_SCHED_INFO flavor of host_info. It has the following members:

int min_timeout

The minimum timeout and unit of time in milliseconds.

int min_quantum

The minimum quantum and unit of quantum in milliseconds.

Data type: host_sched_info_t

This is a pointer to a struct host_sched_info.

Function: kern_return_t host_kernel_version (host_t host, kernel_version_t *version)

The host_kernel_version function returns the version string compiled into the kernel executing on host at the time it was built in the character string version. This string describes the version of the kernel. The constant KERNEL_VERSION_MAX should be used to dimension storage for the returned string if the kernel_version_t declaration is not used.

If the version string compiled into the kernel is longer than KERNEL_VERSION_MAX, the result is truncated and not necessarily null-terminated.

If host is not a valid send right to a host port, the function returns KERN_INVALID_ARGUMENT. If version points to inaccessible memory, it returns KERN_INVALID_ADDRESS, and KERN_SUCCESS otherwise.

Function: kern_return_t host_get_boot_info (host_priv_t host_priv, kernel_boot_info_t boot_info)

The host_get_boot_info function returns the boot-time information string supplied by the operator to the kernel executing on host_priv in the character string boot_info. The constant KERNEL_BOOT_INFO_MAX should be used to dimension storage for the returned string if the kernel_boot_info_t declaration is not used.

If the boot-time information string supplied by the operator is longer than KERNEL_BOOT_INFO_MAX, the result is truncated and not necessarily null-terminated.

8.3 Host Time

Data type: time_value_t

This is the representation of a time in Mach. It is a struct time_value and consists of the following members:

integer_t seconds

The number of seconds.

integer_t microseconds

The number of microseconds.

The number of microseconds should always be smaller than TIME_MICROS_MAX (100000). A time with this property is normalized. Normalized time values can be manipulated with the following macros:

Macro: time_value_add_usec (time_value_t *val, integer_t *micros)

Add micros microseconds to val. If val is normalized and micros smaller than TIME_MICROS_MAX, val will be normalized afterwards.

Macro: time_value_add (time_value_t *result, time_value_t *addend)

Add the values in addend to result. If both are normalized, result will be normalized afterwards.

A variable of type time_value_t can either represent a duration or a fixed point in time. In the latter case, it shall be interpreted as the number of seconds and microseconds after the epoch 1. Jan 1970.

Function: kern_return_t host_get_time (host_t host, time_value_t *current_time)

Get the current time as seen by host. On success, the time passed since the epoch is returned in current_time.

Function: kern_return_t host_set_time (host_priv_t host_priv, time_value_t new_time)

Set the time of host_priv to new_time.

Function: kern_return_t host_adjust_time (host_priv_t host_priv, time_value_t new_adjustment, time_value_t *old_adjustment)

Arrange for the current time as seen by host_priv to be gradually changed by the adjustment value new_adjustment, and return the old adjustment value in old_adjustment.

For efficiency, the current time is available through a mapped-time interface.

Data type: mapped_time_value_t

This structure defines the mapped-time interface. It has the following members:

integer_t seconds

The number of seconds.

integer_t microseconds

The number of microseconds.

integer_t check_seconds

This is a copy of the seconds value, which must be checked to protect against a race condition when reading out the two time values.

Here is an example how to read out the current time using the mapped-time interface:

do 
  {
    secs = mtime->seconds;
    usecs = mtime->microseconds;
  }
while (secs != mtime->check_seconds);

8.4 Host Reboot

Function: kern_return_t host_reboot (host_priv_t host_priv, int options)

Reboot the host specified by host_priv. The argument options specifies the flags. The available flags are defined in `sys/reboot.h':

RB_HALT

Do not reboot, but halt the machine.

RB_DEBUGGER

Do not reboot, but enter kernel debugger from user space.

If successful, the function might not return.