semaphore_create

Function - Create a new semaphore.

SYNOPSIS

kern_return_t	semaphore_create
		(task_t                   task,
		 semaphore_t        *semaphore,
		 int                    policy,
		 int                     value);

PARAMETERS

task

[in task port] The task receiving the send right of the newly created semaphore.

semaphore

[out send right] The port naming the created semaphore.

policy

[in scalar] The blocked thread wakeup policy for the newly created semaphore. Valid policies are:

SYNC_POLICY_FIFO

a first-in-first-out policy for scheduling thread wakeup.

SYNC_POLICY_FIXED_PRIORITY

a fixed priority policy for scheduling thread wakeup.

value

[in scalar] The initial value of the semaphore count.

DESCRIPTION

The semaphore_create function creates a new semaphore, associates the created semaphore with the specified task, and returns a send right naming the new semaphore. In order to support a robust producer/consumer communication service, Interrupt Service Routines (ISR) must be able to signal semaphores. The semaphore synchronizer service is designed to allow user-level device drivers to perform signal operations, eliminating the need for event counters. Device drivers which utilize semaphores are responsible for creating (via semaphore_create) and exporting (via device_get_status) semaphores for user level access. Device driver semaphore creation is done at device initialization time. Device drivers may support multiple semaphores.

RETURN VALUES

KERN_INVALID_ARGUMENT

The task argument or the policy argument was invalid, or the initial value of the semaphore was invalid.

KERN_RESOURCE_SHORTAGE

The kernel could not allocate the semaphore.

KERN_SUCCESS

The semaphore was successfully created.

RELATED INFORMATION

Functions: semaphore_destroy, semaphore_signal, semaphore_signal_all, semaphore_wait, device_get_status.