|
managarm/hel
|
#include <stddef.h>#include <string.h>#include <stdint.h>#include "hel-types.h"Go to the source code of this file.
Classes | |
| struct | HelRegisterInfo |
| Register-related information returned by helQueryRegisterInfo. More... | |
| struct | HelQueue |
| In-memory kernel/user-space queue. More... | |
| struct | HelElement |
| A single element of a HelQueue. More... | |
| struct | HelSqCancel |
| SQ data for kHelSubmitCancel. More... | |
| struct | HelSqExchangeMsgs |
| SQ data for kHelSubmitExchangeMsgs. More... | |
| struct | HelSqAwaitClock |
| SQ data for kHelSubmitAwaitClock. More... | |
| struct | HelSqAwaitEvent |
| SQ data for kHelSubmitAwaitEvent. More... | |
| struct | HelSqProtectMemory |
| SQ data for kHelSubmitProtectMemory. More... | |
| struct | HelSqSynchronizeSpace |
| SQ data for kHelSubmitSynchronizeSpace. More... | |
| struct | HelSqReadMemory |
| SQ data for kHelSubmitReadMemory. More... | |
| struct | HelSqWriteMemory |
| SQ data for kHelSubmitWriteMemory. More... | |
| struct | HelSqManageMemory |
| SQ data for kHelSubmitManageMemory. More... | |
| struct | HelSqLockMemoryView |
| SQ data for kHelSubmitLockMemoryView. More... | |
| struct | HelSqObserve |
| SQ data for kHelSubmitObserve. More... | |
| struct | HelSqResizeMemory |
| SQ data for kHelSubmitResizeMemory. More... | |
| struct | HelSqForkMemory |
| SQ data for kHelSubmitForkMemory. More... | |
Functions | |
Logging | |
| HEL_C_LINKAGE HelError | helLog (const enum HelLogSeverity severity, const char *string, size_t length) |
| Writes a text message (e.g., a line of text) to the kernel's log. | |
| HEL_C_LINKAGE void | helPanic (const char *string, size_t length) __attribute__((noreturn)) |
| Kills the current thread and writes an error message to the kernel's log. | |
Debugging | |
| HEL_C_LINKAGE HelError | helNop () |
| Does nothing (useful only for profiling). | |
| HEL_C_LINKAGE HelError | helSubmitAsyncNop (HelHandle queueHandle, uintptr_t context) |
| Does nothing, asynchronously (useful only for profiling). | |
Management of Descriptors and Universes | |
| HEL_C_LINKAGE HelError | helCreateUniverse (HelHandle *handle) |
| Creates a new universe descriptor. | |
| HEL_C_LINKAGE HelError | helTransferDescriptor (HelHandle handle, HelHandle universeHandle, enum HelTransferDescriptorFlags direction, HelHandle *outHandle) |
| Copies descriptors from the current universe to another universe. | |
| HEL_C_LINKAGE HelError | helGetCredentials (HelHandle handle, uint32_t flags, char *credentials) |
| Returns the credentials associated with a given descriptor. | |
| HEL_C_LINKAGE HelError | helCloseDescriptor (HelHandle universeHandle, HelHandle handle) |
| Closes a descriptor. | |
Management of IPC Queues | |
| HEL_C_LINKAGE HelError | helCreateQueue (const struct HelQueueParameters *params, HelHandle *handle) |
| Creates an IPC queue. | |
| HEL_C_LINKAGE HelError | helDriveQueue (HelHandle queueHandle, uint32_t flags) |
| Drives an IPC queue. | |
| HEL_C_LINKAGE HelError | helAlertQueue (HelHandle queueHandle) |
| Alerts an IPC queue. | |
Memory Management | |
| HEL_C_LINKAGE HelError | helAllocateMemory (size_t size, uint32_t flags, const struct HelAllocRestrictions *restrictions, HelHandle *handle) |
| Creates a memory object consisting of unmanaged RAM. | |
| HEL_C_LINKAGE HelError | helResizeMemory (HelHandle handle, size_t newSize) |
| Resizes a memory object. | |
| HEL_C_LINKAGE HelError | helCreateManagedMemory (size_t size, uint32_t flags, HelHandle *backingHandle, HelHandle *frontalHandle) |
| Creates a memory object that is managed by userspace. | |
| HEL_C_LINKAGE HelError | helCopyOnWrite (HelHandle memory, uintptr_t offset, size_t size, HelHandle *handle) |
| Creates memory object that obtains its memory by copy-on-write from another memory object. | |
| HEL_C_LINKAGE HelError | helCreateIndirectMemory (size_t numSlots, HelHandle *handle) |
| Creates a memory object that obtains its memory by delegating to other memory objects. | |
| HEL_C_LINKAGE HelError | helAlterMemoryIndirection (HelHandle indirectHandle, size_t slotIndex, HelHandle memoryHandle, uintptr_t offset, size_t size) |
| Modifies indirect memory objects. | |
| HEL_C_LINKAGE HelError | helForkMemory (HelHandle handle, HelHandle *forkedHandle) |
| Forks memory objects, i.e., copies them using copy-on-write. | |
| HEL_C_LINKAGE HelError | helCreateSpace (HelHandle *handle) |
| Creates a virtual address space that threads can run in. | |
| HEL_C_LINKAGE HelError | helMapMemory (HelHandle memoryHandle, HelHandle spaceHandle, void *pointer, uintptr_t offset, size_t size, uint32_t flags, void **actualPointer) |
| Maps memory objects into an address space. | |
| HEL_C_LINKAGE HelError | helUnmapMemory (HelHandle spaceHandle, void *pointer, size_t size) |
| Unmaps memory from an address space. | |
| HEL_C_LINKAGE HelError | helLoadahead (HelHandle handle, uintptr_t offset, size_t length) |
| Notifies the kernel that a certain range of memory should be preloaded. | |
Thread Management | |
| HEL_C_LINKAGE HelError | helCreateThread (HelHandle universe, HelHandle spaceHandle, HelAbi abi, void *ip, void *sp, uint32_t flags, HelHandle *handle) |
| Create a new thread. | |
| HEL_C_LINKAGE HelError | helQueryThreadStats (HelHandle handle, struct HelThreadStats *stats) |
| Query run-time statistics of a thread. | |
| HEL_C_LINKAGE HelError | helSetPriority (HelHandle handle, int priority) |
| Set the priority of a thread. | |
| HEL_C_LINKAGE HelError | helYield () |
| Yields the current thread. | |
| HEL_C_LINKAGE HelError | helKillThread (HelHandle handle) |
| Kill (i.e., terminate) a thread. | |
| HEL_C_LINKAGE HelError | helInterruptThread (HelHandle handle) |
| Interrupt a thread. | |
| HEL_C_LINKAGE HelError | helResume (HelHandle handle) |
| Resume a suspended thread. | |
| HEL_C_LINKAGE HelError | helLoadRegisters (HelHandle handle, int set, void *image) |
| Load a register image (e.g., from a thread). | |
| HEL_C_LINKAGE HelError | helStoreRegisters (HelHandle handle, int set, const void *image) |
| Store a register image (e.g., to a thread). | |
| HEL_C_LINKAGE HelError | helQueryRegisterInfo (int set, struct HelRegisterInfo *info) |
| Query register-related information. | |
| HEL_C_LINKAGE HelError | helGetCurrentCpu (int *cpu) |
| Gets the index of the cpu which the calling thread is running on. | |
| HEL_C_LINKAGE HelError | helGetClock (uint64_t *counter) |
| Read the system-wide monotone clock. | |
| HEL_C_LINKAGE HelError | helGetAffinity (HelHandle handle, uint8_t *mask, size_t size, size_t *actualSize) |
| Get a thread's CPU affinity mask. | |
| HEL_C_LINKAGE HelError | helSetAffinity (HelHandle handle, uint8_t *mask, size_t size) |
| Set a thread's CPU affinity mask. | |
Message Passing | |
| HEL_C_LINKAGE HelError | helCreateStream (HelHandle *lane1, HelHandle *lane2, uint32_t attach_credentials) |
| Create a stream (which always consists of two lanes). | |
| HEL_C_LINKAGE HelError | helCreateToken (HelHandle *handle) |
| Create a token object. | |
Inter-Thread Synchronization | |
| HEL_C_LINKAGE HelError | helFutexWait (int *pointer, int expected, int64_t deadline) |
| Waits on a futex. | |
| HEL_C_LINKAGE HelError | helFutexWake (int *pointer, unsigned int count) |
| Wakes up all waiters of a futex. | |
Event Handling | |
| HEL_C_LINKAGE HelError | helCreateOneshotEvent (HelHandle *handle) |
| Create an event that fires at most once. | |
| HEL_C_LINKAGE HelError | helCreateBitsetEvent (HelHandle *handle) |
| Create an event consisting of multiple bits that can fire independently. | |
| HEL_C_LINKAGE HelError | helRaiseEvent (HelHandle handle) |
| Raise an event. | |
Input/Output | |
| HEL_C_LINKAGE HelError | helEnableIo (HelHandle handle) |
| Enable userspace access to hardware I/O resources. | |
Kernlet Management | |
| HEL_C_LINKAGE HelError | helBindKernlet (HelHandle handle, const union HelKernletData *data, size_t numData, HelHandle *boundHandle) |
| Bind parameters to a kernlet. | |
| HEL_C_LINKAGE HelError helAlertQueue | ( | HelHandle | queueHandle | ) |
Alerts an IPC queue.
This function sets the kHelUserNotifyAlert flag in the queue's userNotify and causes helDriveQueue() to return from waiting.
| [in] | queueHandle | Handle to the queue. |
| HEL_C_LINKAGE HelError helAllocateMemory | ( | size_t | size, |
| uint32_t | flags, | ||
| const struct HelAllocRestrictions * | restrictions, | ||
| HelHandle * | handle | ||
| ) |
Creates a memory object consisting of unmanaged RAM.
| [in] | size | Size of the memory object in bytes. Must be aligned to the system's page size. |
| [in] | restrictions | Specifies restrictions for the kernel's memory allocator. May be NULL if there are no restrictions. |
| [out] | handle | Handle to the new memory object. |
| HEL_C_LINKAGE HelError helAlterMemoryIndirection | ( | HelHandle | indirectHandle, |
| size_t | slotIndex, | ||
| HelHandle | memoryHandle, | ||
| uintptr_t | offset, | ||
| size_t | size | ||
| ) |
Modifies indirect memory objects.
| [in] | indirectHandle | Handle to the indirect memory object to be modified. Must refer to a memory object created by helCreateIndirectMemory. |
| [in] | slotIndex | Index of the slot to be modified. Must be a non-negative integer smaller than numSlots (see helCreateIndirectMemory). |
| [in] | memoryHandle | Handle to the memory object that indirectHandle should delegate to. |
| [in] | offset | Offset in bytes, relative to memoryHandle. Must be aligned to the system's page size. |
| [in] | size | Size of the indirection in bytes. Must be aligned to the system's page size. |
| HEL_C_LINKAGE HelError helBindKernlet | ( | HelHandle | handle, |
| const union HelKernletData * | data, | ||
| size_t | numData, | ||
| HelHandle * | boundHandle | ||
| ) |
Bind parameters to a kernlet.
| [in] | handle | Handle to the unbound kernlet. |
| [in] | data | Pointer to an array of binding parameters. |
| [in] | numData | Number of binding parameters in data. |
| [out] | boundHandle | Handle to the bound kernlet. |
| HEL_C_LINKAGE HelError helCloseDescriptor | ( | HelHandle | universeHandle, |
| HelHandle | handle | ||
| ) |
Closes a descriptor.
| [in] | universeHandle | Handle to the universe containing handle. |
| [in] | handle | Handle to be closed. |
| HEL_C_LINKAGE HelError helCopyOnWrite | ( | HelHandle | memory, |
| uintptr_t | offset, | ||
| size_t | size, | ||
| HelHandle * | handle | ||
| ) |
Creates memory object that obtains its memory by copy-on-write from another memory object.
| [in] | memory | Handle to the source memory object. |
| [in] | offset | Offset in byte relative to memory. |
| [in] | size | Size of the memory object in bytes. Must be aligned to the system's page size. |
| [out] | handle | Handle to the new memory object. |
| HEL_C_LINKAGE HelError helCreateBitsetEvent | ( | HelHandle * | handle | ) |
Create an event consisting of multiple bits that can fire independently.
| [out] | handle | Handle to the new event. |
| HEL_C_LINKAGE HelError helCreateIndirectMemory | ( | size_t | numSlots, |
| HelHandle * | handle | ||
| ) |
Creates a memory object that obtains its memory by delegating to other memory objects.
| [in] | numSlots | Number of slots, i.e., other memory objects that the indirect memory object refers to. |
| [out] | handle | Handle to the new memory object. |
| HEL_C_LINKAGE HelError helCreateManagedMemory | ( | size_t | size, |
| uint32_t | flags, | ||
| HelHandle * | backingHandle, | ||
| HelHandle * | frontalHandle | ||
| ) |
Creates a memory object that is managed by userspace.
The backingHandle is used to manage the memory object, while the frontalHandle provides a view on the memory object for consumers.
| [in] | size | Size of the memory object in bytes. Must be aligned to the system's page size. |
| [out] | backingHandle | Handle to the new memory object (for management) |
| [out] | frontalHandle | Handle to the new memory object (for consumers). |
| HEL_C_LINKAGE HelError helCreateOneshotEvent | ( | HelHandle * | handle | ) |
Create an event that fires at most once.
| [out] | handle | Handle to the new event. |
| HEL_C_LINKAGE HelError helCreateQueue | ( | const struct HelQueueParameters * | params, |
| HelHandle * | handle | ||
| ) |
Creates an IPC queue.
| [in] | params | Parameters for the queue. |
| [out] | handle | Handle to the newly created queue. |
| HEL_C_LINKAGE HelError helCreateSpace | ( | HelHandle * | handle | ) |
Creates a virtual address space that threads can run in.
| [out] | handle | Handle to the new address space. |
| HEL_C_LINKAGE HelError helCreateStream | ( | HelHandle * | lane1, |
| HelHandle * | lane2, | ||
| uint32_t | attach_credentials | ||
| ) |
Create a stream (which always consists of two lanes).
| [out] | lane1 | Handle to the first lane of the new stream. |
| [out] | lane2 | Handle to the second lane of the new stream. |
| [in] | attach_credentials | Enable or disable credentials for the new stream. |
| HEL_C_LINKAGE HelError helCreateThread | ( | HelHandle | universe, |
| HelHandle | spaceHandle, | ||
| HelAbi | abi, | ||
| void * | ip, | ||
| void * | sp, | ||
| uint32_t | flags, | ||
| HelHandle * | handle | ||
| ) |
Create a new thread.
| [in] | universeHandle | Handle to universe of the new thread. |
| [in] | spaceHandle | Handle to universe of the new thread. |
| [in] | abi | ABI that the new thread should adhere to. |
| [in] | ip | Instruction pointer of the new thread. |
| [in] | sp | Stack pointer of the new thread. |
| [out] | handle | Handle to the new thread. |
| HEL_C_LINKAGE HelError helCreateToken | ( | HelHandle * | handle | ) |
Create a token object.
A token object represents some unnamed credentials which can be shared. Token objects can be passed to ImbueCredentials to send the credentials they hold instead of the thread's credentials.
| [out] | handle | Handle to the token object |
| HEL_C_LINKAGE HelError helCreateUniverse | ( | HelHandle * | handle | ) |
Creates a new universe descriptor.
| [out] | handle | Handle to the new universe descriptor. |
| HEL_C_LINKAGE HelError helDriveQueue | ( | HelHandle | queueHandle, |
| uint32_t | flags | ||
| ) |
Drives an IPC queue.
This function signals the kernel that new chunks have been supplied and optionally waits for progress on the completion queue.
| [in] | queueHandle | Handle to the queue. |
| [in] | flags | Flags controlling the behavior. If kHelDriveWaitCqProgress is set, the call blocks until progress is made. |
| HEL_C_LINKAGE HelError helEnableIo | ( | HelHandle | handle | ) |
Enable userspace access to hardware I/O resources.
| [in] | handle | Handle to the hardware I/O resource. |
| HEL_C_LINKAGE HelError helForkMemory | ( | HelHandle | handle, |
| HelHandle * | forkedHandle | ||
| ) |
Forks memory objects, i.e., copies them using copy-on-write.
| [in] | indirectHandle | Handle to the memory object to be forked. Must refer to a memory object created by helCopyOnWrite. |
| [out] | handle | Handle to the new (i.e., forked) memory object. |
| HEL_C_LINKAGE HelError helFutexWait | ( | int * | pointer, |
| int | expected, | ||
| int64_t | deadline | ||
| ) |
Waits on a futex.
| [in] | pointer | Pointer that identifies the futex. |
| [in] | expected | Expected value of the futex. This function does nothing unless the futex pointed to by @pointer matches this value. |
| [in] | deadline | Timeout (in absolute monotone time, see helGetClock). |
| HEL_C_LINKAGE HelError helFutexWake | ( | int * | pointer, |
| unsigned int | count | ||
| ) |
Wakes up all waiters of a futex.
| [in] | pointer | Pointer that identifies the futex. |
| [in] | count | Maximum number of waiters to wake. |
| HEL_C_LINKAGE HelError helGetAffinity | ( | HelHandle | handle, |
| uint8_t * | mask, | ||
| size_t | size, | ||
| size_t * | actualSize | ||
| ) |
Get a thread's CPU affinity mask.
| [in] | handle | Handle to the thread. |
| [out] | mask | Buffer to write the affinity bitmask to. |
| [in] | size | Size of bit mask buffer. |
| [out] | actual_size | Amount of bytes actually written to mask. |
| HEL_C_LINKAGE HelError helGetClock | ( | uint64_t * | counter | ) |
Read the system-wide monotone clock.
| [out] | counter | Current value of the system-wide clock in nanoseconds since boot. |
| HEL_C_LINKAGE HelError helGetCredentials | ( | HelHandle | handle, |
| uint32_t | flags, | ||
| char * | credentials | ||
| ) |
Returns the credentials associated with a given descriptor.
| [in] | handle | Handle to the descriptor. |
| [out] | credentials | Credentials, i.e., a 16-byte binary string. |
| HEL_C_LINKAGE HelError helInterruptThread | ( | HelHandle | handle | ) |
Interrupt a thread.
This system call temporarily suspends a thread. The thread can later be resumed through the use of helResume.
| [in] | handle | Handle to the thread. |
| HEL_C_LINKAGE HelError helKillThread | ( | HelHandle | handle | ) |
Kill (i.e., terminate) a thread.
| [in] | handle | Handle to the thread. |
| HEL_C_LINKAGE HelError helLoadahead | ( | HelHandle | handle, |
| uintptr_t | offset, | ||
| size_t | length | ||
| ) |
Notifies the kernel that a certain range of memory should be preloaded.
This acts as a hint to the kernel and is meant purely as a performance optimization. The kernel is free to ignore it.
| [in] | handle | Handle to the memory object. |
| [in] | offset | Offset in bytes, relative to handle. |
| [in] | length | Length of the memory range that is preloaded. |
| HEL_C_LINKAGE HelError helLoadRegisters | ( | HelHandle | handle, |
| int | set, | ||
| void * | image | ||
| ) |
Load a register image (e.g., from a thread).
| [in] | handle | Handle to the thread. |
| [in] | set | Register set that will be accessed. |
| [out] | image | Copy of the register image. |
| HEL_C_LINKAGE HelError helLog | ( | const enum HelLogSeverity | severity, |
| const char * | string, | ||
| size_t | length | ||
| ) |
Writes a text message (e.g., a line of text) to the kernel's log.
| [in] | severity | The RFC 5424 priority of the log message. |
| [in] | string | Text to be written. |
| [in] | length | Size of the text in bytes. |
| HEL_C_LINKAGE HelError helMapMemory | ( | HelHandle | memoryHandle, |
| HelHandle | spaceHandle, | ||
| void * | pointer, | ||
| uintptr_t | offset, | ||
| size_t | size, | ||
| uint32_t | flags, | ||
| void ** | actualPointer | ||
| ) |
Maps memory objects into an address space.
| [in] | memoryHandle | Handle to the memory object. |
| [in] | spaceHandle | Handle to the address space (see helCreateSpace). |
| [in] | pointer | Pointer to which the memory is mapped. Can be specified as NULL to let the kernel pick a pointer. |
| [in] | offset | Offset in bytes, relative to memoryHandle. Must be aligned to the system's page size. |
| [in] | size | Size of the mappping in bytes. Must be aligned to the system's page size. |
| [out] | actualPointer | Pointer to which the memory is mapped. Differs from pointer only if pointer was specified as NULL. |
| HEL_C_LINKAGE void helPanic | ( | const char * | string, |
| size_t | length | ||
| ) |
Kills the current thread and writes an error message to the kernel's log.
| [in] | string | Text to be written. |
| [in] | length | Size of the text in bytes. |
| HEL_C_LINKAGE HelError helQueryRegisterInfo | ( | int | set, |
| struct HelRegisterInfo * | info | ||
| ) |
Query register-related information.
| [in] | set | |
| [out] | info | Returned information. |
| HEL_C_LINKAGE HelError helQueryThreadStats | ( | HelHandle | handle, |
| struct HelThreadStats * | stats | ||
| ) |
Query run-time statistics of a thread.
| [in] | handle | Handle to the thread. |
| [out] | stats | Statistics related to the thread. |
| HEL_C_LINKAGE HelError helRaiseEvent | ( | HelHandle | handle | ) |
Raise an event.
| [in] | handle | Handle to the event that will be raised. |
| HEL_C_LINKAGE HelError helResizeMemory | ( | HelHandle | handle, |
| size_t | newSize | ||
| ) |
Resizes a memory object.
| [in] | handle | Handle to the memory object. Must be aligned to the system's page size. |
| [in] | newSize | New size in bytes. |
| HEL_C_LINKAGE HelError helResume | ( | HelHandle | handle | ) |
Resume a suspended thread.
Threads can explicitly be suspended through the use of helInterruptThread. They are also suspended on faults and supercalls.
| [in] | handle | Handle to the thread. |
| HEL_C_LINKAGE HelError helSetAffinity | ( | HelHandle | handle, |
| uint8_t * | mask, | ||
| size_t | size | ||
| ) |
Set a thread's CPU affinity mask.
| [in] | handle | Handle to the thread. |
| [in] | mask | Pointer to a bit mask of CPUs to schedule on. |
| [in] | size | Size of bit mask. |
| HEL_C_LINKAGE HelError helSetPriority | ( | HelHandle | handle, |
| int | priority | ||
| ) |
Set the priority of a thread.
Managarm always runs the runnable thread with highest priority. The default priority of a thread is zero.
| [in] | handle | Handle to the thread. |
| [in] | priority | New priority value of the thread. |
| HEL_C_LINKAGE HelError helStoreRegisters | ( | HelHandle | handle, |
| int | set, | ||
| const void * | image | ||
| ) |
Store a register image (e.g., to a thread).
| [in] | handle | Handle to the thread. |
| [in] | set | Register set that will be accessed. |
| [in] | image | Copy of the register image. |
| HEL_C_LINKAGE HelError helSubmitAsyncNop | ( | HelHandle | queueHandle, |
| uintptr_t | context | ||
| ) |
Does nothing, asynchronously (useful only for profiling).
This is an asynchronous operation.
| HEL_C_LINKAGE HelError helTransferDescriptor | ( | HelHandle | handle, |
| HelHandle | universeHandle, | ||
| enum HelTransferDescriptorFlags | direction, | ||
| HelHandle * | outHandle | ||
| ) |
Copies descriptors from the current universe to another universe.
| [in] | handle | Handle the descriptor to transfer. |
| [in] | universeHandle | Handle to the destination universe. |
| [out] | outHandle | Handle to the copied descriptor (valid in the universe specified by universeHandle). |
| HEL_C_LINKAGE HelError helUnmapMemory | ( | HelHandle | spaceHandle, |
| void * | pointer, | ||
| size_t | size | ||
| ) |
Unmaps memory from an address space.
| [in] | spaceHandle | Handle to the address space containing pointer. |
| [in] | pointer | Pointer to the mapping that is unmapped. Must be aligned to the system's page size. |
| [in] | size | Size of the mapping that is unmapped. Must be aligned to the system's page size. |