nt-lite/code/public/ntlite/port.h

// Public nt-lite Port IPC declarations. Payload pointers are syscall-local only; queued messages never retain them.

#pragma once

#include <stddef.h>
#include <stdint.h>
#include <ntlite/handle.h>

// Larger transfers should pass a mapping/file-mapping capability instead of enlarging inline messages.
#define SYS_PORT_MAX_INLINE_BYTES      4096u
#define SYS_PORT_MAX_TRANSFER_HANDLES  8u
#define SYS_PORT_DEFAULT_BACKLOG       16u
#define SYS_PORT_MAX_BACKLOG           64u
#define SYS_PORT_QUEUE_MESSAGE_LIMIT   64u
#define SYS_PORT_QUEUE_BYTE_LIMIT      (64u * 1024u)
#define SYS_PORT_QUEUE_HANDLE_LIMIT    128u
#define SYS_PORT_TIMEOUT_INFINITE      UINT64_MAX

#define SYS_PORT_FLAG_NONE 0u

#define SYS_PORT_MESSAGE_NOTIFICATION 1u
#define SYS_PORT_MESSAGE_REQUEST      2u
#define SYS_PORT_MESSAGE_REPLY        3u

// With no flag, DesiredRights creates an attenuated alias of the source grant.
// SAME_RIGHTS requires DesiredRights=0. DERIVE creates a revocable child grant.
#define SYS_PORT_TRANSFER_FLAG_NONE        0u
#define SYS_PORT_TRANSFER_FLAG_SAME_RIGHTS 0x00000001u
#define SYS_PORT_TRANSFER_FLAG_DERIVE      0x00000002u

#define SYS_PORT_ACCEPT_FLAG_NONE 0u
#define SYS_PORT_CONNECT_FLAG_NONE 0u

// Port-specific capability rights.
#define SYS_PORT_RIGHT_CONNECT    0x00000100u
#define SYS_PORT_RIGHT_ACCEPT     0x00000200u
#define SYS_PORT_RIGHT_SEND       0x00000400u
#define SYS_PORT_RIGHT_RECEIVE    0x00000800u
#define SYS_PORT_RIGHT_CALL       0x00001000u
#define SYS_PORT_RIGHT_REPLY             0x00002000u
#define SYS_PORT_RIGHT_DISCONNECT        0x00004000u
#define SYS_PORT_RIGHT_OPEN_PEER_PROCESS 0x00008000u

// Describes one capability that accompanies a Port message.
typedef struct SYS_PORT_HANDLE_TRANSFER {
    SYS_HANDLE Handle;
    SYS_RIGHTS DesiredRights;
    uint32_t Flags;
} SYS_PORT_HANDLE_TRANSFER;

// Describes one delivered Port message. Sender identity is always kernel-stamped.
typedef struct SYS_PORT_MESSAGE_INFO {
    uint32_t Size;
    uint32_t Flags;
    uint32_t MessageId;
    uint32_t Type;
    uint32_t PayloadLength;
    uint32_t HandleCount;
    uint32_t SenderProcessId;
    uint32_t SenderThreadId;
    uint32_t SenderSecurityId;
} SYS_PORT_MESSAGE_INFO;

// Describes the client that created one accepted Port connection.
typedef struct SYS_PORT_CONNECTION_INFO {
    uint32_t Size;
    uint32_t Flags;
    uint32_t ClientProcessId;
    uint32_t ClientThreadId;
    uint32_t ClientSecurityId;
} SYS_PORT_CONNECTION_INFO;

// Creates one connection-listener Port.
typedef struct SYS_CREATE_PORT_REQUEST {
    uint32_t Size;
    uint32_t Flags;
    uint32_t Backlog;
    SYS_RIGHTS PeerProcessRights;
    uint32_t Reserved;
    SYS_HANDLE* HandleOut;
} SYS_CREATE_PORT_REQUEST;

// Connects to one listener capability directly.
typedef struct SYS_CONNECT_PORT_REQUEST {
    uint32_t Size;
    SYS_HANDLE ListenerHandle;
    uint32_t Flags;
    SYS_HANDLE* EndpointHandleOut;
} SYS_CONNECT_PORT_REQUEST;

// Accepts one queued connection from a listener.
typedef struct SYS_ACCEPT_PORT_REQUEST {
    uint32_t Size;
    SYS_HANDLE ListenerHandle;
    uint32_t Flags;
    uint64_t TimeoutMilliseconds;
    SYS_HANDLE* EndpointHandleOut;
    SYS_PORT_CONNECTION_INFO* ConnectionInfoOut;
} SYS_ACCEPT_PORT_REQUEST;

// Sends one one-way notification to the peer endpoint.
typedef struct SYS_SEND_PORT_REQUEST {
    uint32_t Size;
    SYS_HANDLE EndpointHandle;
    uint32_t Flags;
    const void* Payload;
    uint32_t PayloadLength;
    const SYS_PORT_HANDLE_TRANSFER* Handles;
    uint32_t HandleCount;
    uint64_t TimeoutMilliseconds;
} SYS_SEND_PORT_REQUEST;

// Receives one request or notification from the endpoint.
typedef struct SYS_RECEIVE_PORT_REQUEST {
    uint32_t Size;
    SYS_HANDLE EndpointHandle;
    uint32_t Flags;
    void* Payload;
    uint32_t PayloadCapacity;
    SYS_HANDLE* HandlesOut;
    uint32_t HandleCapacity;
    SYS_PORT_MESSAGE_INFO* InfoOut;
    uint64_t TimeoutMilliseconds;
} SYS_RECEIVE_PORT_REQUEST;

// Sends a synchronous request and receives its reply. Timeout zero returns WOULD_BLOCK without sending.
typedef struct SYS_CALL_PORT_REQUEST {
    uint32_t Size;
    SYS_HANDLE EndpointHandle;
    uint32_t Flags;
    const void* RequestPayload;
    uint32_t RequestLength;
    const SYS_PORT_HANDLE_TRANSFER* RequestHandles;
    uint32_t RequestHandleCount;
    void* ReplyPayload;
    uint32_t ReplyCapacity;
    SYS_HANDLE* ReplyHandlesOut;
    uint32_t ReplyHandleCapacity;
    SYS_PORT_MESSAGE_INFO* ReplyInfoOut;
    uint64_t TimeoutMilliseconds;
} SYS_CALL_PORT_REQUEST;

// Replies to one synchronous request identified by MessageId.
typedef struct SYS_REPLY_PORT_REQUEST {
    uint32_t Size;
    SYS_HANDLE EndpointHandle;
    uint32_t MessageId;
    uint32_t Flags;
    const void* Payload;
    uint32_t PayloadLength;
    const SYS_PORT_HANDLE_TRANSFER* Handles;
    uint32_t HandleCount;
} SYS_REPLY_PORT_REQUEST;

// Port metadata and transfer descriptors cross the kernel/userspace boundary.
_Static_assert(sizeof(SYS_PORT_HANDLE_TRANSFER) == 12u, "SYS_PORT_HANDLE_TRANSFER ABI size changed");
_Static_assert(sizeof(SYS_PORT_MESSAGE_INFO) == 36u, "SYS_PORT_MESSAGE_INFO ABI size changed");
_Static_assert(offsetof(SYS_PORT_MESSAGE_INFO, SenderSecurityId) == 32u,
               "SYS_PORT_MESSAGE_INFO sender identity offset changed");
_Static_assert(sizeof(SYS_PORT_CONNECTION_INFO) == 20u, "SYS_PORT_CONNECTION_INFO ABI size changed");