/*
 * Copyright (c) 2018 Apple Inc. All rights reserved.
 *
 * @APPLE_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. 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_LICENSE_HEADER_END@
 */

/*!
 * @header
 * Darwin-specific interfaces for manipulating Mach exception handling
 * properties of a task.
 */
#ifndef __DARWIN_EXCEPTION_H
#define __DARWIN_EXCEPTION_H

#include <os/base.h>
#include <os/api.h>

#include <sys/cdefs.h>
#include <spawn.h>

#include <mach/mach.h>
#include <mach/port.h>
#include <mach/mach_port.h>
#include <mach/kern_return.h>

#if DARWIN_TAPI
#include "tapi.h"
#endif

__BEGIN_DECLS;

/*!
 * @typedef os_crash_flags_t
 * A flagset describing crash handling behaviors.
 *
 * @param OS_CRASH_FLAG_INIT
 * Handle no exceptions.
 *
 * @param OS_CRASH_FLAG_CRASH
 * Handle exceptions due to crashing conditions (e.g. segmentation violations,
 * signals raise(3)ed manually, etc.). These exceptions will suspend the subject
 * task until the exception handler has returned.
 *
 * @param OS_CRASH_FLAG_GUARD
 * Handle exceptions due to the subject task violating guarded kernel handles
 * (e.g. guarded mach port rights and file descriptors).
 *
 * @param OS_CRASH_FLAG_RESOURCE
 * Handle exceptions due to the subject task exceeding resource usage limits
 * (e.g. CPU spins, memory growth, etc.).
 *
 * @param OS_CRASH_FLAG_CORPSE
 * Handle exceptions which create corpses. The subject task of these exceptions
 * is a corpse of the original task, which is torn down asynchronously. Corpses
 * are a limited representation of the original task that is suitable for most
 * introspection needs.
 *
 * This flag is mutually exclusive with {@link OS_CRASH_FLAG_CRASH}, and if both
 * are present, this flag will be preferred.
 *
 * @discussion
 * There are other Mach exception types than the ones enumerated by these flags,
 * but they are almost exclusively handled internally by the kernel, and
 * therefore are of little interest to userspace. Those that are not handled by
 * the kernel are only relevant to debuggers.
 */
OS_ENUM(os_crash_flags, uint32_t,
	OS_CRASH_FLAG_INIT = 0,
	OS_CRASH_FLAG_CRASH = (1 << 0),
	OS_CRASH_FLAG_GUARD = (1 << 1),
	OS_CRASH_FLAG_RESOURCE = (1 << 2),
	OS_CRASH_FLAG_CORPSE = (1 << 3),
);

/*!
 * @enum os_crash_type_t
 * A type describing exception types relevant to userspace crash reporters.
 * These values serve as indexes into a {@link os_crash_port_array_t}.
 *
 * @const OS_CRASH_NONE
 * No exception type.
 *
 * @const OS_CRASH_CRASH
 * A crashing exception with the behavior described in {@link OS_CRASH_FLAG_CRASH}.
 *
 * @const OS_CRASH_GUARD
 * A guard exception with the behavior described in {@link OS_CRASH_FLAG_GUARD}.
 *
 * @const OS_CRASH_RESOURCE
 * A resource exception with the behavior described in {@link OS_CRASH_FLAG_RESOURCE}.
 *
 * @const OS_CRASH_CORPSE
 * A corpse exception with the behavior described in {@link OS_CRASH_FLAG_CORPSE}.
 */
OS_ENUM(os_crash_type, uint32_t,
	OS_CRASH_NONE,
	OS_CRASH_CRASH,
	OS_CRASH_GUARD,
	OS_CRASH_RESOURCE,
	OS_CRASH_CORPSE,
	_OS_CRASH_LAST,
);

/*!
 * struct os_crash_port_t
 * A type describing an exception port and the exception it handles.
 *
 * @property oep_type
 * The type of exception handled by the port.
 *
 * @property oep_port
 * A handle representing a send right to the exception port.
 */
DARWIN_API_AVAILABLE_20170407
typedef struct _os_crash_port {
	os_crash_type_t oep_type;
	mach_port_t oep_port;
} os_crash_port_t;

/*!
 * @define DARWIN_EXCEPTION_PORT_ARRAY_COUNT
 * The maximum number of exception ports that an exception port array can
 * accommodate.
 */
#define OS_CRASH_PORT_ARRAY_COUNT (16lu)

/*!
 * @typedef os_crash_port_array_t
 * An array of exception ports. This array can accommodate all exception types
 * described in the {@link os_crash_type_t} type and is sized to
 * accommodate future exception types.
 */
DARWIN_API_AVAILABLE_20170407
typedef os_crash_port_t os_crash_port_array_t[OS_CRASH_PORT_ARRAY_COUNT];

/*!
 * @function os_crash_set_reporter_port
 * Routine to set the exception handler port for the exceptions given.
 *
 * @param where
 * The task port or host port for which to set the exception handler. This
 * routine will internally choose the proper method of setting the exception
 * port based on whether this parameter represents the host or not.
 *
 * @param flags
 * Flags describing which exceptions are to be handled by the port.
 *
 * @param p
 * A send right to the desired exception handler port.
 *
 * @result
 * A kernel return code.
 *
 * @discussion
 * This routine automatically chooses the most expressive thread state to
 * deliver in the exception message based on the current architecture.
 */
DARWIN_API_AVAILABLE_20170407
OS_EXPORT OS_WARN_RESULT
kern_return_t
os_crash_set_reporter_port(mach_port_t where,
		os_crash_flags_t flags, mach_port_t p);

/*!
 * @function os_crash_get_reporter_port_array
 * Routine to get the ports which handle exceptions for all enumerated exception
 * types in {@link os_crash_flags_t}.
 *
 * @param where
 * The task port or host port for which to retrieve exception handler ports.
 * This routine will internally choose the proper method of obtaining the
 * exception ports based on whether this parameter represents the host or not.
 *
 * @param array
 * An array describing the exception ports for the target host or task. This
 * array must be disposed of with {@link os_crash_port_array_deallocate}
 * when it is no longer needed.
 *
 * @result
 * A kernel return code.
 */
DARWIN_API_AVAILABLE_20170407
OS_EXPORT OS_WARN_RESULT OS_NONNULL2
kern_return_t
os_crash_get_reporter_port_array(mach_port_t where,
		os_crash_port_array_t array);

/*!
 * @function os_crash_port_array_deallocate
 * Routine to deallocate an array of exception port descriptors.
 *
 * @param array
 * The array which is to be disposed of.
 *
 * @discussion
 * This routine disposes of the resources represented by the kernel handles in
 * the array. It does not manipulate the array's memory. The expectation is that
 * the caller allocates {@link os_crash_port_array_t} from the stack.
 */
DARWIN_API_AVAILABLE_20170407
OS_EXPORT OS_NONNULL1
void
os_crash_port_array_deallocate(os_crash_port_array_t array);

/*!
 * @function os_crash_spawnattr_set_reporter_port
 * Routine to set the exception handler port for the exceptions given in a
 * posix_spawn(2) attributes structure.
 *
 * @param psattr
 * The spawn attributes for which the exception port should be set.
 *
 * @param flags
 * Flags describing which exceptions are to be handled by the port.
 *
 * @param p
 * A send right to the desired exception handler port.
 *
 * @result
 * A kernel return code. This routine will only fail if the port name given was
 * invalid.
 */
DARWIN_API_AVAILABLE_20170407
OS_EXPORT OS_WARN_RESULT OS_NONNULL1
kern_return_t
os_crash_spawnattr_set_reporter_port(posix_spawnattr_t *psattr,
		os_crash_flags_t flags, mach_port_t p);

__END_DECLS;

#endif // __DARWIN_EXCEPTION_H