playbit / docs / runtime

Runtime system calls

#include <playbit/sys/syscalls.h>

System calls are guest->host operations routed through pb_syscall / pb_syscall_async. runtime/include/playbit/sys/syscalls/*.h provides the C wrappers.

Conventions

Audio

PBSysAudioBufferCreate

PBSysAudioBuffer PBSysAudioBufferCreate(PBSysHandle audio,
                                        const void* data,
                                        usize       dataSize,
                                        u32         numChannels,
                                        u32         sampleRate,
                                        u32         totalSampleCount);

Creates a new audio buffer and uploads it to the sound mixer.

PBSysAudioBufferCreateFromFile

PBSysAudioBuffer PBSysAudioBufferCreateFromFile(PBSysHandle audio,
                                                const void* data,
                                                usize       dataSize);

Creates an audio buffer from a file. At the present moment, we only support raw WAV file data. This function will be extended in the future to support more formats.

PBSysAudioBufferDestroy

PBSysErr PBSysAudioBufferDestroy(PBSysHandle      audio,
                                 PBSysAudioBuffer buffer);

Destroys an audio buffer (and frees the associated memory with it).

PBSysAudioBufferPlay

PBSysAudioSound PBSysAudioBufferPlay(PBSysHandle      audio,
                                     PBSysAudioBuffer buffer);

Starts playing an instance of an audio buffer.

PBSysAudioOutputInit

bool PBSysAudioOutputInit(PBSysHandle audio);

Inits the audio output backend for sound playback (globally). It has been observed that sometimes this can take a little while (e.g. ~200ms when using bluetooth headphones on MacOS). As such, you should call this at the start of your program if you intend to play audio.

PBSysAudioSetVolume

PBSysErr PBSysAudioSetVolume(PBSysHandle audio,
                             f32         volume);

Sets the global volume of the sound mixer.

Bundle

PBSysBundleGetResource

i64 PBSysBundleGetResource(PBSysHandle bundle,
                           const u8*   name,
                           usize       nameLen,
                           u8*         dest,
                           usize       destLen);

PBSysBundleGetResource retrieves a bundles resource, as described by the app's manifest at build time.

Channel

PBSysChannelCreate

PBSysHandle PBSysChannelCreate(u32          entSize,
                               u32          cap,
                               u32          maxCap,
                               PBSysHandle* readHandleOut,
                               u64          flags);

PBSysChannelCreate creates a channel which supports writing entries of entSize bytes.

If the PBSysChannel_DUPLEX flag is set, the returned handles will have both PBSysRight_READ and PBSysRight_WRITE. PBSysChannel_DUPLEX is implied if readHandleOut is NULL.

If the PBSysChannel_MULTIPLE_WRITERS flag is set, the returned handle will have PBSysRight_DUPLICATE. Similarly, if the PBSysChannel_MULTIPLE_READERS flag is set, a handle returned in readHandleOut will have PBSysRight_DUPLICATE.

PBSysChannelDisableWrite

PBSysErr PBSysChannelDisableWrite(PBSysHandle channel);

PBSysChannelDisableWrite disables the ability to write to the channel, while reading remains possible. This is useful for "graceful shutdown" of channels; preventing new data from being produces while allowing queued data to be flushed.

PBSysChannelRead

i32 PBSysChannelRead(PBSysHandle channel,
                     void*       dstEnts,
                     u32         dstEntSize,
                     u32         dstEntsCap,
                     u64         flags);

PBSysChannelRead reads up to dstEntsCap entries from a channel.

Panics if srcEntSize is different than the entSize the channel was created with.

PBSysChannelWrite

i32 PBSysChannelWrite(PBSysHandle channel,
                      const void* srcEnts,
                      u32         srcEntSize,
                      u32         srcEntsCap,
                      u64         flags);

PBSysChannelWrite writes up to srcEntsCap entries to a channel.

Panics if srcEntSize is different than the entSize the channel was created with.

Clock

PBSysClockMonotonic

PBSysTime PBSysClockMonotonic();

PBSysClockMonotonic returns the current system time

PBSysClockRead

PBSysDate PBSysClockRead(PBSysHandle clock);

PBSysClockRead returns the current "real" (calendar) time in UTC. On error, a PBSysErr is returned as a negative value. Thus, this function never returns a time value earlier than 1970-01-01 00:00:00.

PBSysClockReadInfo

PBSysErr PBSysClockReadInfo(PBSysHandle     clock,
                            PBSysClockInfo* info,
                            u32             infoSize);

PBSysClockReadInfo retrieves information about a clock

Event

PBSysEventPoll

i32 PBSysEventPoll(PBSysEvent* events,
                   u32         eventsSize,
                   u64         deadline,
                   u64         deadlineLeeway);

PBSysEventPoll retrieves events from the runtime, suspending the calling thread if needed.

FileList

PBSysFileListNext

i32 PBSysFileListNext(PBSysHandle         fileList,
                      u8*                 name,
                      u32                 nameCap,
                      PBSysFileListEntry* entry,
                      u32                 entrySize,
                      u64                 flags);

PBSysFileListNextName read the name of the next entry in a directory listing.

File

PBSysFileListOpen

PBSysHandle PBSysFileListOpen(PBSysHandle dir,
                              const u8*   path,
                              u32         pathLen,
                              u64         flags);

PBSysFileListOpen begins a list operation of the directory dir/path, or dir if pathLen is 0. Call PBSysFileListNext to retrieve entries and PBSysHandleClose when done.

PBSysFileOpen

PBSysHandle PBSysFileOpen(PBSysHandle dir,
                          const u8*   path,
                          u32         pathLen,
                          u64         flags);

PBSysFileOpen opens a file or directory that's contained within a directory denoted by dir.

The effective rights given to the opened file must be the same or a subset of the rights given to the fs handle. I.e. on a read-only filesystem you cannot pass PBSysFileOpenFlag_WRITE.

The resulting handle is given PBSysRight_TRANSFER and PBSysRight_DUPLICATE, in addition to PBSysRight_READ and/or PBSysRight_WRITE as defined by flags.

PBSysFileRead

i64 PBSysFileRead(PBSysHandle     file,
                  const PBSysBuf* bufs,
                  u32             bufCount,
                  u32             flags);

PBSysFileRead reads bytes from a file at its current read cursor into one or more buffers.

Note: Currently only synchronous reads are supported. Returns PBSysErr_NOT_SUPPORTED unless PBSysFileReadFlag_SYNC is set.

PBSysFileWrite

i64 PBSysFileWrite(PBSysHandle     file,
                   const PBSysBuf* bufs,
                   u32             bufCount,
                   u32             flags);

PBSysFileWrite writes bytes from one or more buffers to a file at the file's current write cursor.

Note: Currently only synchronous writes are supported. Returns PBSysErr_NOT_SUPPORTED unless PBSysFileWriteFlag_SYNC is set.

Gui

PBSysGuiCursorStyleSet

PBSysErr PBSysGuiCursorStyleSet(PBSysHandle      gui,
                                u32              pointerId,
                                PBSysCursorStyle style,
                                PBSysHandle      image,
                                u64              flags);

PBSysGuiCursorStyleSet sets the appearance of specified pointer's cursor.

Handle

PBSysHandleClose

PBSysErr PBSysHandleClose(PBSysHandle handle);

PBSysHandleClose closes a handle. The handle is invalid after this call.

PBSysHandleDuplicate

PBSysHandle PBSysHandleDuplicate(PBSysHandle     handle,
                                 PBSysRights     rights,
                                 PBSysHandleName name);

PBSysHandleDuplicate creates a new handle to the object referred to by handle. rights controls what rights are given and can only be same or less than the rights granted to handle. Use PBSysRight_SAME_RIGHTS for "same rights." Note: The new handle is unconditionally given PBSysRight_TRANSFER.

PBSysHandleList

i32 PBSysHandleList(PBSysHandleInfo* handles,
                    u32              handlesCap,
                    u32              handleSize,
                    u64              flags,
                    u64              predicate);

PBSysHandleList returns information about handles held by the calling thread. Writes up to handlesCap entries to handles.

flags are bits of PBSysHandleListFlags.

If flags contain a filter; a PBSysHandleListFilter value in the bits PBSysHandleList_FILTER, then predicate is a value for the filter. Only handles matching the filter are returned.

Net

PBSysNetConnect

PBSysHandle PBSysNetConnect(PBSysHandle                  net,
                            const u8*                    uri,
                            u32                          uriLen,
                            const PBSysNetConnectConfig* config,
                            u32                          configSize);

PBSysNetConnect opens a stream connected to a network endpoint.

URIs have the form protocol:node, i.e.

tcp:host:port  TCP/IP socket
local:path     Local socket (aka UNIX socket)

The underlying implementation may not support the requested protocol.

The returned stream will have its PBSysStreamSignal_WRITABLE activated when the connection has been established.

PBSysNetSessionOpen

PBSysHandle PBSysNetSessionOpen(PBSysHandle                  net,
                                const u8*                    sessionId,
                                u32                          sessionIdLen,
                                const PBSysNetSessionConfig* config,
                                u32                          configSize);

PBSysNetSessionOpen opens a Playbit network session

NetSession

PBSysNetSessionId

PBSysErr PBSysNetSessionId(PBSysHandle netSession,
                           u8*         sessionIdBuf,
                           u32         sessionIdBufCap);

PBSysNetSessionId copies the session identifier bytes of a network session.

PBSysNetSessionOpenStream

PBSysHandle PBSysNetSessionOpenStream(PBSysHandle netSession,
                                      const u8*   channelId,
                                      u32         channelIdLen,
                                      u64         flags);

PBSysNetSessionOpenStream opens a stream for a channel in a network session.

Object

PBSysObjectObserve

PBSysErr PBSysObjectObserve(PBSysHandle  handle,
                            PBSysSignals signals,
                            u32          flags);

PBSysObjectObserve configures signal observation of the object referred to by handle.

Signal observation is "level" triggered by default, meaning that whenever an observed signal becomes active, a PBSysEventLegacy.signal is produced, until you cancel observation by calling this function with signals=0. By setting the PBSysObjectObserve_ONCE flag, the behavior changes to be "edge" triggered, where one PBSysObjectObserve call yields just one signal event. If you want to keep observing an object after a signal event in "edge" triggered mode, you need to issue another call to PBSysObjectObserve. ONCE is manily useful for one-off observers of e.g. single-fire timers or threads.

Setting signals to 0 has the effect of canceling observation. If PBSysObjectObserve_ADD is set in flags, setting signals to 0 is an error (PBSysErr_INVALID).

This function may be called multiple times to modify what signals are observed.

PBSysObjectSignal

PBSysErr PBSysObjectSignal(PBSysHandle  handle,
                           PBSysSignals disableUserSignals,
                           PBSysSignals enableUserSignals,
                           PBSysSignals pulseUserSignals);

PBSysObjectSignal clear and/or sets user signals for handle.

First disableUserSignals are applied then enableUserSignals.

Stream

PBSysStreamOpenPipePair

PBSysErr PBSysStreamOpenPipePair(PBSysHandle* handlesOut,
                                 u32          bufferSize,
                                 u64          flags);

PBSysStreamOpenPipePair creates two connected duplex byte streams.

Writes to one handle become readable from the other handle and vice versa.

PBSysStreamRead

i64 PBSysStreamRead(PBSysHandle     stream,
                    const PBSysBuf* bufs,
                    u32             bufCount,
                    u32             flags);

PBSysStreamRead reads bytes from a stream into one or more buffers.

PBSysStreamStatsRead

PBSysErr PBSysStreamStatsRead(PBSysHandle       stream,
                              PBSysStreamStats* stats,
                              u32               statsSize,
                              u64               flags);

PBSysStreamStatsRead retrieves statistics for a stream.

PBSysStreamWrite

i64 PBSysStreamWrite(PBSysHandle     stream,
                     const PBSysBuf* bufs,
                     u32             bufCount,
                     u32             flags);

PBSysStreamWrite writes bytes from one or more buffers to a stream.

Textplan

PBSysTextplanGetCaretBounds

u64 PBSysTextplanGetCaretBounds(PBSysHandle textPlan,
                                u64         caretTextIndex);

PBSysTextplanGetSelectionRects

u64 PBSysTextplanGetSelectionRects(PBSysHandle                 textPlan,
                                   u64                         selectionStart,
                                   u64                         selectionEnd,
                                   PBSysTextplanSelectionRect* rects,
                                   u32                         rectsCap,
                                   u32                         rectSize);

PBSysTextplanGetSelectionRects retrieves line-wise selection rectangles relative to the text plan origin.

PBSysTextplanGetSize

u64 PBSysTextplanGetSize(PBSysHandle textPlan);

PBSysTextplanGetSize: Get the size of a text plan's layout.

textPlan: The text plan object.

Return value: The width and height of the plan. The macros PBTextplanWidthOfSize and PBTextplanHeightOfSize can be used to extract the two values from the return value of the function. The returned width is the width of the widest line in the plan in pixels. The returned height is the distance from the top of the first line to the bottom of the last line in pixels.

This function gives no information about where text glyphs may actually be drawn. Glyphs can extend outside the boundaries of the line on which they are placed.

You must call PBSysTextplanLayout before calling this function.

PBSysTextplanHitTest

u64 PBSysTextplanHitTest(PBSysHandle textPlan,
                         i32         x,
                         i32         y);

PBSysTextplanLayout

i64 PBSysTextplanLayout(PBSysHandle textPlan,
                        u32         flags,
                        i32         width,
                        i32         height);

PBSysTextplanLayout lays a text document into a rectangular bounding box.

textPlan: The text plan to contain the resulting layout.

flags: Flags bitwise OR-ed together controlling the text layout operation. The available flags are

width: The width of the rectangular bounding box in pixels. Set to 0 for infinite space (and thus preventing line wrapping or truncation).

height: The height of the rectangular bounding box in pixels. Set to 0 for infinite space.

If the system detects that the new bounding box will not affect the existing layout in the text plan, this function will do nothing.

This function performs text shaping and then places the resulting glyphs into lines. If a line were to go off the right side of the box, it will either be truncated with an ellipsis character or wrap to a new line, depending on whether PBTextPlanLayout_ONE_LINE is set.

Once this function has been called, you can use the other text plan functions.

PBSysTextplanMoveSelection

bool PBSysTextplanMoveSelection(PBSysHandle             textPlan,
                                u32                     mode,
                                PBSysTextplanSelection* selection,
                                u32                     selectionSize);

PBSysTextplanMoveSelection updates a selection using selection-adjustment flags without hit testing a point.

PBSysTextplanMoveSelectionToPoint

bool PBSysTextplanMoveSelectionToPoint(PBSysHandle             textPlan,
                                       u32                     mode,
                                       i32                     x,
                                       i32                     y,
                                       PBSysTextplanSelection* selection,
                                       u32                     selectionSize);

PBSysTextplanMoveSelectionToPoint updates a selection by hit-testing a point and applying selection-adjustment flags.

PBSysTextplanMoveSelectionVertical

bool PBSysTextplanMoveSelectionVertical(PBSysHandle             textPlan,
                                        i32                     preferredX,
                                        bool                    upwards,
                                        bool                    extend,
                                        PBSysTextplanSelection* selection,
                                        u32                     selectionSize);

PBSysTextplanMoveSelectionVertical moves a selection up or down by one visual line while preserving a preferred x position.

Texture

PBSysTextureWrite

PBSysErr PBSysTextureWrite(PBSysHandle texture,
                           u32         originXInPx,
                           u32         originYInPx,
                           const void* pixels,
                           u64         pixelSize,
                           u32         widthInPx,
                           u32         heightInPx);

PBSysTextureWrite uploads pixel data to a region of a texture. Pixels must be in the format the texture was created with (RGBA8: 4 bytes per pixel, row-major).

Thread

PBSysThreadEnterMain

void PBSysThreadEnterMain(u64 flags);

PBSysThreadEnterMain

PBSysThreadExit

PBSysErr PBSysThreadExit(PBSysHandle thread,
                         i32         status);

PBSysThreadExit stops a thread and sets its exit status.

PBSysThreadExitProcess

PBSysErr PBSysThreadExitProcess(PBSysHandle thread,
                                i32         status);

PBSysThreadExitProcess terminated the process.

PBSysThreadExitStatus

i32 PBSysThreadExitStatus(PBSysHandle thread);

PBSysThreadExitStatus returns the exit status of thread.

PBSysThreadHostControllerConnect

PBSysHandle PBSysThreadHostControllerConnect(PBSysHandle thread);

Note: Draft API; arguments will change

PBSysThreadLogWrite

PBSysErr PBSysThreadLogWrite(PBSysHandle     thread,
                             const PBSysBuf* bufs,
                             u32             bufCount,
                             u32             flags);

PBSysThreadLogWrite writes to the runtime log sink for a thread.

PBSysThreadNetConnect

PBSysHandle PBSysThreadNetConnect(PBSysHandle thread,
                                  u32         ipAddr,
                                  u16         tcpPort);

Note: Draft API; arguments will change

PBSysThreadRead

PBSysErr PBSysThreadRead(void*        data,
                         u32*         dataSizeInOut,
                         PBSysHandle* handles,
                         u32*         handlesCountInOut,
                         u64          flags);

PBSysThreadRead receives a message sent to the calling thread.

Messages may contain both byte data and handle payloads and may only be read in their entirety. Partial reads are not possible.

PBSysThreadStart

PBSysHandle PBSysThreadStart(PBSysHandle              parentThread,
                             u64                      flags,
                             const PBSysThreadConfig* config,
                             u64                      configSize);

PBSysThreadStart starts a new thread.

PBSysThreadWindowCreate

PBSysHandle PBSysThreadWindowCreate(PBSysHandle              thread,
                                    const PBSysWindowConfig* config,
                                    usize                    configSize);

PBSysThreadWindowCreate creates a window associated with a thread.

PBSysThreadWrite

PBSysErr PBSysThreadWrite(PBSysHandle        thread,
                          const void*        data,
                          u32                dataSize,
                          const PBSysHandle* handles,
                          u32                handlesCount,
                          u64                flags);

PBSysThreadWrite sends a message to a thread. data is copied.

Window

PBSysWindowClipboardReadText

i64 PBSysWindowClipboardReadText(PBSysHandle window,
                                 u8*         buffer,
                                 u64         bufferSize);

PBSysWindowClipboardWriteText reads the text from the clipboard.

PBSysWindowClipboardWriteText

PBSysErr PBSysWindowClipboardWriteText(PBSysHandle window,
                                       const u8*   text,
                                       u64         textSize);

PBSysWindowClipboardWriteText sets the text on the clipboard.

PBSysWindowCopyTitle

i32 PBSysWindowCopyTitle(PBSysHandle window,
                         u8*         buf,
                         u32         bufCap,
                         u64         flags);

PBSysWindowCopyTitle retrieves the title of a window.

PBSysWindowCreateTexture

PBSysHandle PBSysWindowCreateTexture(PBSysHandle                   window,
                                     PBSysTextureFormat            format,
                                     u32                           widthInPx,
                                     u32                           heightInPx,
                                     PBSysWindowCreateTextureFlags flags);

PBSysWindowCreateTexture creates an RGBA8 texture associated with a window. The texture can be uploaded to via PBSysTextureWrite and set as the active texture for shape draw calls via a TEXTURE_SET renderer instruction.

PBSysWindowCreateTextureFromData

PBSysHandle PBSysWindowCreateTextureFromData(PBSysHandle                   window,
                                             PBSysTextureFormat            format,
                                             const void*                   data,
                                             u64                           dataSize,
                                             PBSysWindowCreateTextureFlags flags);

PBSysWindowCreateTextureFromData decodes image data and creates a GPU texture in one step. Supported formats: PNG, JPEG, WebP, GIF, BMP, TGA. Pixels are always decoded to RGBA8. The format parameter must be PBSysTextureFormat_RGBA8.

PBSysWindowFrameSyncEnable

PBSysErr PBSysWindowFrameSyncEnable(PBSysHandle window,
                                    u64         flags);

PBSysWindowFrameSyncEnable controls the production of FRAME_SYNC pulses.

PBSysWindowInfoGet

PBSysErr PBSysWindowInfoGet(PBSysHandle      window,
                            PBSysWindowInfo* info,
                            u64              infoSize);

PBSysWindowInfoGet retrieves latest window metrics and timing hints.

PBSysWindowRendererPackageWrite

PBSysErr PBSysWindowRendererPackageWrite(PBSysHandle                       window,
                                         const PBSysWindowRendererPackage* package,
                                         usize                             packageSize);

PBSysWindowRendererPackageWrite submits renderer package data for a window.

PBSysWindowSetRect

PBSysErr PBSysWindowSetRect(PBSysHandle             window,
                            f32                     x,
                            f32                     y,
                            f32                     width,
                            f32                     height,
                            PBSysWindowSetRectFlags flags);

PBSysWindowSetRect sets the position and size of a window. The actual size of the window may be larger if the size is smaller than the minimum possible window size, according to the host OS.

x & y sets the position on screen of the top-left corner of the window, with a top-left origin. x and y are ignored if PBSysWindowSetRectFlag_CENTER is set.

PBSysWindowSetStyle

PBSysErr PBSysWindowSetStyle(PBSysHandle      window,
                             PBSysWindowStyle style,
                             u64              flags);

PBSysWindowSetStyle sets the style of a window.

PBSysWindowSetTitle

PBSysErr PBSysWindowSetTitle(PBSysHandle window,
                             const u8*   text,
                             u64         textLen);

PBSysWindowSetTitle sets the title of a window.

PBSysWindowSizeLimitsSet

PBSysErr PBSysWindowSizeLimitsSet(PBSysHandle window,
                                  f32         minWidth,
                                  f32         minHeight,
                                  f32         maxWidth,
                                  f32         maxHeight,
                                  u64         flags);

PBSysWindowSizeLimits sets lower and upper frame size limits.

Use negative numbers to keep values unchanged.

PBSysWindowTextplanCreate

PBSysHandle PBSysWindowTextplanCreate(PBSysHandle window,
                                      const u8*   text,
                                      u64         textSize,
                                      u32         fontFamily,
                                      u32         size,
                                      u32         weight,
                                      u32         color);

PBSysWindowTextplanCreate creates a text plan object associated with a window.

TODO: Proper positioned attributes array.

Notes

See also ABI, Types, and System events.