/*++
Copyright (c) 1989 Microsoft Corporation
Module Name:
semphore.c
Abstract:
This module implements the executive semaphore object. Functions are
provided to create, open, release, and query semaphore objects.
Author:
David N. Cutler (davec) 8-May-1989
Environment:
Kernel mode only.
Revision History:
--*/
#include "exp.h"
//
// Temporary so boost is patchable
//
ULONG ExpSemaphoreBoost = SEMAPHORE_INCREMENT;
//
// Address of semaphore object type descriptor.
//
POBJECT_TYPE ExSemaphoreObjectType;
//
// Structure that describes the mapping of generic access rights to object
// specific access rights for semaphore objects.
//
GENERIC_MAPPING ExpSemaphoreMapping = {
STANDARD_RIGHTS_READ |
SEMAPHORE_QUERY_STATE,
STANDARD_RIGHTS_WRITE |
SEMAPHORE_MODIFY_STATE,
STANDARD_RIGHTS_EXECUTE |
SYNCHRONIZE,
SEMAPHORE_ALL_ACCESS
};
#ifdef ALLOC_PRAGMA
#pragma alloc_text(INIT, ExpSemaphoreInitialization)
#pragma alloc_text(PAGE, NtCreateSemaphore)
#pragma alloc_text(PAGE, NtOpenSemaphore)
#pragma alloc_text(PAGE, NtQuerySemaphore)
#pragma alloc_text(PAGE, NtReleaseSemaphore)
#endif
BOOLEAN
ExpSemaphoreInitialization (
)
/*++
Routine Description:
This function creates the semaphore object type descriptor at system
initialization and stores the address of the object type descriptor
in local static storage.
Arguments:
None.
Return Value:
A value of TRUE is returned if the semaphore object type descriptor is
successfully created. Otherwise a value of FALSE is returned.
--*/
{
OBJECT_TYPE_INITIALIZER ObjectTypeInitializer;
NTSTATUS Status;
UNICODE_STRING TypeName;
//
// Initialize string descriptor.
//
RtlInitUnicodeString(&TypeName, L"Semaphore");
//
// Create semaphore object type descriptor.
//
RtlZeroMemory(&ObjectTypeInitializer, sizeof(ObjectTypeInitializer));
ObjectTypeInitializer.Length = sizeof(ObjectTypeInitializer);
ObjectTypeInitializer.InvalidAttributes = OBJ_OPENLINK;
ObjectTypeInitializer.GenericMapping = ExpSemaphoreMapping;
ObjectTypeInitializer.PoolType = NonPagedPool;
ObjectTypeInitializer.DefaultNonPagedPoolCharge = sizeof(KSEMAPHORE);
ObjectTypeInitializer.ValidAccessMask = SEMAPHORE_ALL_ACCESS;
Status = ObCreateObjectType(&TypeName,
&ObjectTypeInitializer,
(PSECURITY_DESCRIPTOR)NULL,
&ExSemaphoreObjectType);
//
// If the semaphore object type descriptor was successfully created, then
// return a value of TRUE. Otherwise return a value of FALSE.
//
return (BOOLEAN)(NT_SUCCESS(Status));
}
NTSTATUS
NtCreateSemaphore (
IN PHANDLE SemaphoreHandle,
IN ACCESS_MASK DesiredAccess,
IN POBJECT_ATTRIBUTES ObjectAttributes OPTIONAL,
IN LONG InitialCount,
IN LONG MaximumCount
)
/*++
Routine Description:
This function creates a semaphore object, sets its initial count to the
specified value, sets its maximum count to the specified value, and opens
a handle to the object with the specified desired access.
Arguments:
SemaphoreHandle - Supplies a pointer to a variable that will receive the
semaphore object handle.
DesiredAccess - Supplies the desired types of access for the semaphore
object.
ObjectAttributes - Supplies a pointer to an object attributes structure.
InitialCount - Supplies the initial count of the semaphore object.
MaximumCount - Supplies the maximum count of the semaphore object.
Return Value:
TBS
--*/
{
HANDLE Handle;
KPROCESSOR_MODE PreviousMode;
PVOID Semaphore;
NTSTATUS Status;
//
// Establish an exception handler, probe the output handle address, and
// attempt to create a semaphore object. If the probe fails, then return
// the exception code as the service status. Otherwise return the status
// value returned by the object insertion routine.
//
try {
//
// Get previous processor mode and probe output handle address if
// necessary.
//
PreviousMode = KeGetPreviousMode();
if (PreviousMode != KernelMode) {
ProbeForWriteHandle(SemaphoreHandle);
}
//
// Check argument validity.
//
if ((MaximumCount <= 0) || (InitialCount < 0) ||
(InitialCount > MaximumCount)) {
return STATUS_INVALID_PARAMETER;
}
//
// Allocate semaphore object.
//
Status = ObCreateObject(PreviousMode,
ExSemaphoreObjectType,
ObjectAttributes,
PreviousMode,
NULL,
sizeof(KSEMAPHORE),
0,
0,
(PVOID *)&Semaphore);
//
// If the semaphore object was successfully allocated, then initialize
// the semaphore object and attempt to insert the semaphore object in
// the current process' handle table.
//
if (NT_SUCCESS(Status)) {
KeInitializeSemaphore((PKSEMAPHORE)Semaphore,
InitialCount,
MaximumCount);
Status = ObInsertObject(Semaphore,
NULL,
DesiredAccess,
0,
(PVOID *)NULL,
&Handle);
//
// If the semaphore object was successfully inserted in the current
// process' handle table, then attempt to write the semaphore handle
// value. If the write attempt fails, then do not report an error.
// When the caller attempts to access the handle value, an access
// violation will occur.
//
if (NT_SUCCESS(Status)) {
try {
*SemaphoreHandle = Handle;
} except(ExSystemExceptionFilter()) {
}
}
}
//
// If an exception occurs during the probe of the output handle address,
// then always handle the exception and return the exception code as the
// status value.
//
} except(ExSystemExceptionFilter()) {
return GetExceptionCode();
}
//
// Return service status.
//
return Status;
}
NTSTATUS
NtOpenSemaphore (
OUT PHANDLE SemaphoreHandle,
IN ACCESS_MASK DesiredAccess,
IN POBJECT_ATTRIBUTES ObjectAttributes
)
/*++
Routine Description:
This function opens a handle to a semaphore object with the specified
desired access.
Arguments:
SemaphoreHandle - Supplies a pointer to a variable that will receive the
semaphore object handle.
DesiredAccess - Supplies the desired types of access for the semaphore
object.
ObjectAttributes - Supplies a pointer to an object attributes structure.
Return Value:
TBS
--*/
{
HANDLE Handle;
KPROCESSOR_MODE PreviousMode;
NTSTATUS Status;
//
// Establish an exception handler, probe the output handle address, and
// attempt to open a semaphore object. If the probe fails, then return
// the exception code as the service status. Otherwise return the status
// value returned by the object open routine.
//
try {
//
// Get previous processor mode and probe output handle address if
// necessary.
//
PreviousMode = KeGetPreviousMode();
if (PreviousMode != KernelMode) {
ProbeForWriteHandle(SemaphoreHandle);
}
//
// Open handle to the semaphore object with the specified desired access.
//
Status = ObOpenObjectByName(ObjectAttributes,
ExSemaphoreObjectType,
PreviousMode,
NULL,
DesiredAccess,
NULL,
&Handle);
//
// If the open was successful, then attempt to write the semaphore
// object handle value. If the write attempt fails, then do not report
// an error. When the caller attempts to access the handle value, an
// access violation will occur.
//
if (NT_SUCCESS(Status)) {
try {
*SemaphoreHandle = Handle;
} except(ExSystemExceptionFilter()) {
}
}
//
// If an exception occurs during the probe of the output handle address,
// then always handle the exception and return the exception code as the
// status value.
//
} except(ExSystemExceptionFilter()) {
return GetExceptionCode();
}
//
// Return service status.
//
return Status;
}
NTSTATUS
NtQuerySemaphore (
IN HANDLE SemaphoreHandle,
IN SEMAPHORE_INFORMATION_CLASS SemaphoreInformationClass,
OUT PVOID SemaphoreInformation,
IN ULONG SemaphoreInformationLength,
OUT PULONG ReturnLength OPTIONAL
)
/*++
Routine Description:
This function queries the state of a semaphore object and returns the
requested information in the specified record structure.
Arguments:
SemaphoreHandle - Supplies a handle to a semaphore object.
SemaphoreInformationClass - Supplies the class of information being
requested.
SemaphoreInformation - Supplies a pointer to a record that is to receive
the requested information.
SemaphoreInformationLength - Supplies the length of the record that is
to receive the requested information.
ReturnLength - Supplies an optional pointer to a variable that will
receive the actual length of the information that is returned.
Return Value:
TBS
--*/
{
PVOID Semaphore;
LONG Count;
LONG Maximum;
KPROCESSOR_MODE PreviousMode;
NTSTATUS Status;
//
// Establish an exception handler, probe the output arguments, reference
// the semaphore object, and return the specified information. If the probe
// fails, then return the exception code as the service status. Otherwise
// return the status value returned by the reference object by handle
// routine.
//
try {
//
// Get previous processor mode and probe output arguments if necessary.
//
PreviousMode = KeGetPreviousMode();
if (PreviousMode != KernelMode) {
ProbeForWrite(SemaphoreInformation,
sizeof(SEMAPHORE_BASIC_INFORMATION),
sizeof(ULONG));
if (ARGUMENT_PRESENT(ReturnLength)) {
ProbeForWriteUlong(ReturnLength);
}
}
//
// Check argument validity.
//
if (SemaphoreInformationClass != SemaphoreBasicInformation) {
return STATUS_INVALID_INFO_CLASS;
}
if (SemaphoreInformationLength != sizeof(SEMAPHORE_BASIC_INFORMATION)) {
return STATUS_INFO_LENGTH_MISMATCH;
}
//
// Reference semaphore object by handle.
//
Status = ObReferenceObjectByHandle(SemaphoreHandle,
SEMAPHORE_QUERY_STATE,
ExSemaphoreObjectType,
PreviousMode,
&Semaphore,
NULL);
//
// If the reference was successful, then read the current state and
// maximum count of the semaphore object, dereference semaphore object,
// fill in the information structure, and return the length of the
// information structure if specified. If the write of the semaphore
// information or the return length fails, then do not report an error.
// When the caller accesses the information structure or length an
// access violation will occur.
//
if (NT_SUCCESS(Status)) {
Count = KeReadStateSemaphore((PKSEMAPHORE)Semaphore);
Maximum = ((PKSEMAPHORE)Semaphore)->Limit;
ObDereferenceObject(Semaphore);
try {
((PSEMAPHORE_BASIC_INFORMATION)SemaphoreInformation)->CurrentCount = Count;
((PSEMAPHORE_BASIC_INFORMATION)SemaphoreInformation)->MaximumCount = Maximum;
if (ARGUMENT_PRESENT(ReturnLength)) {
*ReturnLength = sizeof(SEMAPHORE_BASIC_INFORMATION);
}
} except(ExSystemExceptionFilter()) {
}
}
//
// If an exception occurs during the probe of the output arguments, then
// always handle the exception and return the exception code as the status
// value.
//
} except(ExSystemExceptionFilter()) {
return GetExceptionCode();
}
//
// Return service status.
//
return Status;
}
NTSTATUS
NtReleaseSemaphore (
IN HANDLE SemaphoreHandle,
IN LONG ReleaseCount,
OUT PLONG PreviousCount OPTIONAL
)
/*++
Routine Description:
This function releases a semaphore object by adding the specified release
count to the current value.
Arguments:
Semaphore - Supplies a handle to a semaphore object.
ReleaseCount - Supplies the release count that is to be added to the
current semaphore count.
PreviousCount - Supplies an optional pointer to a variable that will
receive the previous semaphore count.
Return Value:
TBS
--*/
{
LONG Count;
PVOID Semaphore;
KPROCESSOR_MODE PreviousMode;
NTSTATUS Status;
//
// Establish an exception handler, probe the previous count address if
// specified, reference the semaphore object, and release the semaphore
// object. If the probe fails, then return the exception code as the
// service status. Otherwise return the status value returned by the
// reference object by handle routine.
//
try {
//
// Get previous processor mode and probe previous count address
// if necessary.
//
PreviousMode = KeGetPreviousMode();
if ((PreviousMode != KernelMode) && (ARGUMENT_PRESENT(PreviousCount))) {
ProbeForWriteLong(PreviousCount);
}
//
// Check argument validity.
//
if (ReleaseCount <= 0) {
return STATUS_INVALID_PARAMETER;
}
//
// Reference semaphore object by handle.
//
Status = ObReferenceObjectByHandle(SemaphoreHandle,
SEMAPHORE_MODIFY_STATE,
ExSemaphoreObjectType,
PreviousMode,
&Semaphore,
NULL);
//
// If the reference was successful, then release the semaphore object.
// If an exception occurs because the maximum count of the semaphore
// has been exceeded, then dereference the semaphore object and return
// the exception code as the service status. Otherwise write the previous
// count value if specified. If the write of the previous count fails,
// then do not report an error. When the caller attempts to access the
// previous count value, an access violation will occur.
//
if (NT_SUCCESS(Status)) {
try {
Count = KeReleaseSemaphore((PKSEMAPHORE)Semaphore,
ExpSemaphoreBoost,
ReleaseCount,
FALSE);
ObDereferenceObject(Semaphore);
if (ARGUMENT_PRESENT(PreviousCount)) {
try {
*PreviousCount = Count;
} except(ExSystemExceptionFilter()) {
}
}
} except(ExSystemExceptionFilter()) {
ObDereferenceObject(Semaphore);
return GetExceptionCode();
}
}
//
// If an exception occurs during the probe of the previous count, then
// always handle the exception and return the exception code as the status
// value.
//
} except(ExSystemExceptionFilter()) {
return GetExceptionCode();
}
//
// Return service status.
//
return Status;
}
