1.9 KiB
Host port ABI v0
This ABI exists to test Ada/V interoperability. It is not a syscall ABI and is not stable for production applications.
The C header in include/agila_ports.h is the shared declaration. All identity, handle, and message-value fields are uint32_t. Status values are C int: 0 success, 1 invalid handle, 2 permission denied, 3 full, 4 empty, 5 exhausted, 6 invalid argument. The Ada library uses GNAT's automatic elaboration for a shared standalone library.
agila_port_create(owner) returns a nonzero handle or zero if the owner is zero or every slot is active/retired. The core Ada API distinguishes those failures; the initial host wrapper intentionally has the smaller return shape.
The owner can grant one additional sender, replace that sender, revoke that exact grant, receive, and close. The owner retains its own send permission. Sender zero is invalid. Revocation does not remove accepted messages. Closing clears the queue and invalidates the handle. A rejected operation does not insert or remove a message.
agila_port_receive(handle, caller, value) requires either a valid writable pointer to a uint32_t, or NULL. NULL returns invalid argument. On other failures a valid output pointer receives zero. Arbitrary invalid pointers are outside this trusted host ABI contract; the wrapper does not attempt to probe application memory. A future kernel API must validate/copy user buffers through a different boundary.
Calls must be serialized by the host application. The library does not implement locking, separate processes, caller authentication, transport, persistence, or shared-memory ownership. The generation-checked handle is not a secret authorization token.
The V demonstration covers denied sends, grant, send/receive, revocation, close, and stale-reference rejection. The C test covers NULL and full-width unsigned values. The Ada tests cover ring wrap, FIFO order, exhaustion, permission failures, and independent ports.