[syscalls][docs] Cross-link syscall documentation
This uses the format [`zx_syscall()`] inline, and defines a reference at
the bottom of the file, to avoid having to stutter the syscall name both
as inline text and as the .md file in () after the []. The references at
the bottom of the file are not included in rendered output. (Thanks
bruce.mitchener for the suggested format.)
Additionally, replace existing spellings of syscalls that vary in style,
sometimes prefixing with zx_, sometimes including () inside bold,
sometimes both, and sometimes neither. On a syscall's own page, it is
not linked, and is instead simply `zx_syscall()`. There are some
existing references to syscalls (primarily those that were already
linked) that are not updated by this. Maybe later, or manually.
See the gitiles link for channel_call.md for an example result.
ZX-3106 #comment [syscalls][docs] Cross-link syscall documentation
Test: CQ
Change-Id: Icac7c50251012af3580c130553d1bfd640fb3eff
diff --git a/docs/syscalls/bti_create.md b/docs/syscalls/bti_create.md
index 8a63b3a..3d496be 100644
--- a/docs/syscalls/bti_create.md
+++ b/docs/syscalls/bti_create.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**bti_create**() creates a new [bus transaction initiator](../objects/bus_transaction_initiator.md)
+`zx_bti_create()` creates a new [bus transaction initiator](../objects/bus_transaction_initiator.md)
given a handle to an IOMMU and a hardware transaction identifier for a device
downstream of that IOMMU.
@@ -39,7 +39,7 @@
## RETURN VALUE
-**bti_create**() returns **ZX_OK** and a handle to the new BTI
+`zx_bti_create()` returns **ZX_OK** and a handle to the new BTI
(via *out*) on success. In the event of failure, a negative error value
is returned.
diff --git a/docs/syscalls/bti_pin.md b/docs/syscalls/bti_pin.md
index 49230c8..d49960f 100644
--- a/docs/syscalls/bti_pin.md
+++ b/docs/syscalls/bti_pin.md
@@ -25,7 +25,7 @@
## DESCRIPTION
-**bti_pin**() pins pages of a VMO (i.e. prevents them from being decommitted
+`zx_bti_pin()` pins pages of a VMO (i.e. prevents them from being decommitted
with **[vmo_op_range](vmo_op_range.md)**()) and grants the hardware
transaction ID represented by the BTI the ability to access these pages,
with the permissions specified in *options*.
@@ -38,7 +38,7 @@
READ/WRITE rights corresponding to the permissions flags set in *options*.
(Note: *ZX_BTI_PERM_EXECUTE* requires *ZX_RIGHT_READ*, not *ZX_RIGHT_EXECUTE*.)
*ZX_BTI_CONTIGUOUS* is only allowed if *vmo* was allocated via
-**zx_vmo_create_contiguous**() or **zx_vmo_create_physical**().
+[`zx_vmo_create_contiguous()`] or [`zx_vmo_create_physical()`].
*ZX_BTI_COMPRESS* and *ZX_BTI_CONTIGUOUS* are mutually exclusive.
If the range in *vmo* specified by *offset* and *size* contains non-committed
@@ -86,7 +86,7 @@
## RETURN VALUE
-On success, **bti_pin**() returns *ZX_OK*. The device-physical addresses of the
+On success, `zx_bti_pin()` returns *ZX_OK*. The device-physical addresses of the
requested VMO pages will be written in *addrs*. A handle to the created Pinned
Memory Token is returned via *pmt*. When the PMT is no longer needed,
*pmt_unpin*() should be invoked.
@@ -120,3 +120,8 @@
[bti_create](bti_create.md),
[pmt_unpin](pmt_unpin.md),
[object_get_info](object_get_info.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_vmo_create_contiguous()`]: vmo_create_contiguous.md
+[`zx_vmo_create_physical()`]: vmo_create_physical.md
diff --git a/docs/syscalls/bti_release_quarantine.md b/docs/syscalls/bti_release_quarantine.md
index c663cea..b490fb2 100644
--- a/docs/syscalls/bti_release_quarantine.md
+++ b/docs/syscalls/bti_release_quarantine.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**bti_release_quarantine**() releases all quarantined PMTs for the given BTI.
+`zx_bti_release_quarantine()` releases all quarantined PMTs for the given BTI.
This will release the PMTs' underlying references to VMOs and physical page
pins. The underlying physical pages may be eligible to be reallocated
afterwards.
@@ -31,7 +31,7 @@
## RETURN VALUE
-**bti_release_quarantine**() returns **ZX_OK** on success.
+`zx_bti_release_quarantine()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/cache_flush.md b/docs/syscalls/cache_flush.md
index f58d464..34aa450 100644
--- a/docs/syscalls/cache_flush.md
+++ b/docs/syscalls/cache_flush.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**zx_cache_flush**() flushes CPU caches covering memory in the given
+`zx_cache_flush()` flushes CPU caches covering memory in the given
virtual address range. If that range of memory is not readable, then
the thread may fault as it would for a data read.
@@ -54,7 +54,7 @@
## RETURN VALUE
-**zx_cache_flush**() returns **ZX_OK** on success, or an error code on failure.
+`zx_cache_flush()` returns **ZX_OK** on success, or an error code on failure.
## ERRORS
diff --git a/docs/syscalls/channel_call.md b/docs/syscalls/channel_call.md
index 2550b16..6844415 100644
--- a/docs/syscalls/channel_call.md
+++ b/docs/syscalls/channel_call.md
@@ -23,21 +23,21 @@
## DESCRIPTION
-**channel_call**() is like a combined **channel_write**(), **object_wait_one**(),
-and **channel_read**(), with the addition of a feature where a transaction id at
+`zx_channel_call()` is like a combined [`zx_channel_write()`], [`zx_object_wait_one()`],
+and [`zx_channel_read()`], with the addition of a feature where a transaction id at
the front of the message payload *bytes* is used to match reply messages with send
messages, enabling multiple calling threads to share a channel without any additional
userspace bookkeeping.
-The write and read phases of this operation behave like **channel_write**() and
-**channel_read**() with the difference that their parameters are provided via the
+The write and read phases of this operation behave like [`zx_channel_write()`] and
+[`zx_channel_read()`] with the difference that their parameters are provided via the
*zx_channel_call_args_t* structure.
The first four bytes of the written and read back messages are treated as a
transaction ID of type **zx_txid_t**. The kernel generates a txid for the
written message, replacing that part of the message as read from userspace.
The kernel generated txid will be between 0x80000000 and 0xFFFFFFFF, and will
-not collide with any txid from any other **channel_call**() in progress against
+not collide with any txid from any other `zx_channel_call()` in progress against
this channel endpoint. If the written message has a length of fewer than four
bytes, an error is reported.
@@ -46,7 +46,7 @@
While *deadline* has not passed, if an inbound message arrives with a matching txid,
instead of being added to the tail of the general inbound message queue, it is delivered
-directly to the thread waiting in **zx_channel_call**().
+directly to the thread waiting in `zx_channel_call()`.
If such a reply arrives after *deadline* has passed, it will arrive in the general
inbound message queue, cause **ZX_CHANNEL_READABLE** to be signaled, etc.
@@ -54,8 +54,8 @@
Inbound messages that are too large to fit in *rd_num_bytes* and *rd_num_handles*
are discarded and **ZX_ERR_BUFFER_TOO_SMALL** is returned in that case.
-As with **zx_channel_write**(), the handles in *handles* are always consumed by
-**zx_channel_call**() and no longer exist in the calling process.
+As with [`zx_channel_write()`], the handles in *handles* are always consumed by
+`zx_channel_call()` and no longer exist in the calling process.
## RIGHTS
@@ -67,7 +67,7 @@
## RETURN VALUE
-**channel_call**() returns **ZX_OK** on success and the number of bytes and
+`zx_channel_call()` returns **ZX_OK** on success and the number of bytes and
count of handles in the reply message are returned via *actual_bytes* and
*actual_handles*, respectively.
@@ -105,21 +105,21 @@
## NOTES
-The facilities provided by **channel_call**() can interoperate with message dispatchers
-using **channel_read**() and **channel_write**() directly, provided the following rules
+The facilities provided by `zx_channel_call()` can interoperate with message dispatchers
+using [`zx_channel_read()`] and [`zx_channel_write()`] directly, provided the following rules
are observed:
-1. A server receiving synchronous messages via **channel_read**() should ensure that the
-txid of incoming messages is reflected back in outgoing responses via **channel_write**()
-so that clients using **channel_call**() can correctly route the replies.
+1. A server receiving synchronous messages via [`zx_channel_read()`] should ensure that the
+txid of incoming messages is reflected back in outgoing responses via [`zx_channel_write()`]
+so that clients using `zx_channel_call()` can correctly route the replies.
-2. A client sending messages via **channel_write**() that will be replied to should ensure
+2. A client sending messages via [`zx_channel_write()`] that will be replied to should ensure
that it uses txids between 0 and 0x7FFFFFFF only, to avoid colliding with other threads
-communicating via **channel_call**().
+communicating via `zx_channel_call()`.
-If a **channel_call**() returns due to **ZX_ERR_TIMED_OUT**, if the server eventually replies,
+If a `zx_channel_call()` returns due to **ZX_ERR_TIMED_OUT**, if the server eventually replies,
at some point in the future, the reply *could* match another outbound request (provided about
-2^31 **channel_call**()s have happened since the original request. This syscall is designed
+2^31 `zx_channel_call()`s have happened since the original request. This syscall is designed
around the expectation that timeouts are generally fatal and clients do not expect to continue
communications on a channel that is timing out.
@@ -134,3 +134,9 @@
[channel_create](channel_create.md),
[channel_read](channel_read.md),
[channel_write](channel_write.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_channel_read()`]: channel_read.md
+[`zx_channel_write()`]: channel_write.md
+[`zx_object_wait_one()`]: object_wait_one.md
diff --git a/docs/syscalls/channel_create.md b/docs/syscalls/channel_create.md
index a9dcffd..fd8263e 100644
--- a/docs/syscalls/channel_create.md
+++ b/docs/syscalls/channel_create.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**channel_create**() creates a channel, a bi-directional
+`zx_channel_create()` creates a channel, a bi-directional
datagram-style message transport capable of sending raw data bytes
as well as handles from one side to the other.
@@ -42,7 +42,7 @@
## RETURN VALUE
-**channel_create**() returns **ZX_OK** on success. In the event
+`zx_channel_create()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/channel_read.md b/docs/syscalls/channel_read.md
index 6c80a97..3021f07 100644
--- a/docs/syscalls/channel_read.md
+++ b/docs/syscalls/channel_read.md
@@ -25,7 +25,7 @@
## DESCRIPTION
-**channel_read**() attempts to read the first message from the channel
+`zx_channel_read()` attempts to read the first message from the channel
specified by *handle* into the provided *bytes* and/or *handles* buffers.
The parameters *num_bytes* and *num_handles* are used to specify the
diff --git a/docs/syscalls/channel_read_etc.md b/docs/syscalls/channel_read_etc.md
index 0fa1e85..0f85e21 100644
--- a/docs/syscalls/channel_read_etc.md
+++ b/docs/syscalls/channel_read_etc.md
@@ -27,8 +27,8 @@
See [channel_read](channel_read.md) for a full description.
-Both forms of read behave the same except that **channel_read**() returns an
-array of raw ``zx_handle_t`` handle values while **channel_read_etc**() returns
+Both forms of read behave the same except that [`zx_channel_read()`] returns an
+array of raw ``zx_handle_t`` handle values while `zx_channel_read_etc()` returns
an array of ``zx_handle_info_t`` structures of the form:
```
@@ -41,7 +41,7 @@
```
When communicating to an untrusted party over a channel, it is recommended
-that the **channel_read_etc**() form is used and each handle type and rights
+that the `zx_channel_read_etc()` form is used and each handle type and rights
are validated against the expected values.
## RIGHTS
@@ -98,3 +98,7 @@
[channel_create](channel_create.md),
[channel_read](channel_read.md),
[channel_write](channel_write.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_channel_read()`]: channel_read.md
diff --git a/docs/syscalls/channel_write.md b/docs/syscalls/channel_write.md
index d91ff29..d3472d6 100644
--- a/docs/syscalls/channel_write.md
+++ b/docs/syscalls/channel_write.md
@@ -23,7 +23,7 @@
## DESCRIPTION
-**channel_write**() attempts to write a message of *num_bytes*
+`zx_channel_write()` attempts to write a message of *num_bytes*
bytes and *num_handles* handles to the channel specified by
*handle*. The pointers *handles* and *bytes* may be NULL if their
respective sizes are zero.
@@ -54,7 +54,7 @@
## RETURN VALUE
-**channel_write**() returns **ZX_OK** on success.
+`zx_channel_write()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/clock_get.md b/docs/syscalls/clock_get.md
index 69127a8..6512e75 100644
--- a/docs/syscalls/clock_get.md
+++ b/docs/syscalls/clock_get.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**zx_clock_get**() returns the current time of *clock_id*, or 0 if *clock_id* is
+`zx_clock_get()` returns the current time of *clock_id*, or 0 if *clock_id* is
invalid.
## SUPPORTED CLOCK IDS
@@ -37,8 +37,8 @@
## RETURN VALUE
-On success, **zx_clock_get**() returns the current time according to the given clock ID.
+On success, `zx_clock_get()` returns the current time according to the given clock ID.
## ERRORS
-On error, **zx_clock_get**() returns 0.
+On error, `zx_clock_get()` returns 0.
diff --git a/docs/syscalls/clock_get_monotonic.md b/docs/syscalls/clock_get_monotonic.md
index 9c7f0c6..e16b23d 100644
--- a/docs/syscalls/clock_get_monotonic.md
+++ b/docs/syscalls/clock_get_monotonic.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**zx_clock_get_monotonic**() returns the current time in the system
+`zx_clock_get_monotonic()` returns the current time in the system
monotonic clock. This is the number of nanoseconds since the system was
powered on.
@@ -30,8 +30,12 @@
## RETURN VALUE
-**zx_clock_get**() returns the current monotonic time.
+[`zx_clock_get()`] returns the current monotonic time.
## ERRORS
-**zx_clock_get_monotonic**() cannot fail.
+`zx_clock_get_monotonic()` cannot fail.
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_clock_get()`]: clock_get.md
diff --git a/docs/syscalls/clock_get_new.md b/docs/syscalls/clock_get_new.md
index e2dbf77..b1ae7f9 100644
--- a/docs/syscalls/clock_get_new.md
+++ b/docs/syscalls/clock_get_new.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**zx_clock_get_new** returns the current time of *clock_id* via
+`zx_clock_get_new()` returns the current time of *clock_id* via
*out*, and returns whether *clock_id* was valid.
## SUPPORTED CLOCK IDS
@@ -37,7 +37,7 @@
## RETURN VALUE
-On success, **zx_clock_get_new**() returns *ZX_OK*.
+On success, `zx_clock_get_new()` returns *ZX_OK*.
## ERRORS
diff --git a/docs/syscalls/cprng_add_entropy.md b/docs/syscalls/cprng_add_entropy.md
index 575891c..e4cfc32 100644
--- a/docs/syscalls/cprng_add_entropy.md
+++ b/docs/syscalls/cprng_add_entropy.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**zx_cprng_add_entropy**() mixes the given entropy into the kernel CPRNG.
+`zx_cprng_add_entropy()` mixes the given entropy into the kernel CPRNG.
a privileged operation. It will accept at most **ZX_CPRNG_ADD_ENTROPY_MAX_LEN**
bytes of entropy at a time.
@@ -30,7 +30,7 @@
## RETURN VALUE
-**zx_cprng_add_entropy**() returns **ZX_OK** on success.
+`zx_cprng_add_entropy()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/cprng_draw.md b/docs/syscalls/cprng_draw.md
index 46835e4..5dcf44b 100644
--- a/docs/syscalls/cprng_draw.md
+++ b/docs/syscalls/cprng_draw.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**zx_cprng_draw**() draws random bytes from the kernel CPRNG. This data should
+`zx_cprng_draw()` draws random bytes from the kernel CPRNG. This data should
be suitable for cryptographic applications.
Clients that require a large volume of randomness should consider using these
@@ -32,8 +32,8 @@
## NOTES
-**zx_cprng_draw**() triggers terminates the calling process if **buffer** is not
+`zx_cprng_draw()` triggers terminates the calling process if **buffer** is not
a valid userspace pointer.
There are no other error conditions. If its arguments are valid,
-**zx_cprng_draw**() will succeed.
+`zx_cprng_draw()` will succeed.
diff --git a/docs/syscalls/deadline_after.md b/docs/syscalls/deadline_after.md
index 205558b..e80fd19 100644
--- a/docs/syscalls/deadline_after.md
+++ b/docs/syscalls/deadline_after.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**zx_deadline_after**() is a utility for converting from now-relative durations
+`zx_deadline_after()` is a utility for converting from now-relative durations
to absolute deadlines. If *nanoseconds* plus the current time is bigger than the
maximum value for ``zx_time_t``, the output is clamped to **ZX_TIME_INFINITE**.
@@ -30,12 +30,12 @@
## RETURN VALUE
-**zx_deadline_after**() returns the absolute time (with respect to **CLOCK_MONOTONIC**)
+`zx_deadline_after()` returns the absolute time (with respect to **CLOCK_MONOTONIC**)
that is *nanoseconds* nanoseconds from now.
## ERRORS
-**zx_deadline_after**() does not report any error conditions.
+`zx_deadline_after()` does not report any error conditions.
## EXAMPLES
diff --git a/docs/syscalls/event_create.md b/docs/syscalls/event_create.md
index 8f17995..89dc065 100644
--- a/docs/syscalls/event_create.md
+++ b/docs/syscalls/event_create.md
@@ -18,9 +18,9 @@
## DESCRIPTION
-**event_create**() creates an event, which is an object that is signalable. That
+`zx_event_create()` creates an event, which is an object that is signalable. That
is, its *ZX_USER_SIGNAL_n* (where *n* is 0 through 7) signals can be
-manipulated using **object_signal**().
+manipulated using [`zx_object_signal()`].
The newly-created handle will have the [basic
rights](../rights.md#zx_rights_basic) plus *ZX_RIGHT_SIGNAL*.
@@ -33,7 +33,7 @@
## RETURN VALUE
-**event_create**() returns ZX_OK and a valid event handle (via *out*) on success.
+`zx_event_create()` returns ZX_OK and a valid event handle (via *out*) on success.
On failure, an error value is returned.
## ERRORS
@@ -54,3 +54,7 @@
[object_wait_many](object_wait_many.md),
[handle_replace](handle_replace.md),
[object_signal](object_signal.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_object_signal()`]: object_signal.md
diff --git a/docs/syscalls/eventpair_create.md b/docs/syscalls/eventpair_create.md
index 86f93a0..6a95824 100644
--- a/docs/syscalls/eventpair_create.md
+++ b/docs/syscalls/eventpair_create.md
@@ -20,12 +20,12 @@
## DESCRIPTION
-**eventpair_create**() creates an event pair, which is a pair of objects that
+`zx_eventpair_create()` creates an event pair, which is a pair of objects that
are mutually signalable.
The signals *ZX_EVENTPAIR_SIGNALED* and *ZX_USER_SIGNAL_n* (where *n* is 0 through 7)
-may be set or cleared using **object_signal**() (modifying the signals on the
-object itself), or **object_signal_peer**() (modifying the signals on its
+may be set or cleared using [`zx_object_signal()`] (modifying the signals on the
+object itself), or [`zx_object_signal_peer()`] (modifying the signals on its
counterpart).
When all the handles to one of the objects have been closed, the
@@ -46,7 +46,7 @@
## RETURN VALUE
-**eventpair_create**() returns **ZX_OK** on success. On failure, a (negative)
+`zx_eventpair_create()` returns **ZX_OK** on success. On failure, a (negative)
error code is returned.
@@ -72,3 +72,8 @@
[handle_replace](handle_replace.md),
[object_signal](object_signal.md),
[object_signal_peer](object_signal.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_object_signal()`]: object_signal.md
+[`zx_object_signal_peer()`]: object_signal_peer.md
diff --git a/docs/syscalls/fifo_create.md b/docs/syscalls/fifo_create.md
index d2d81a7..24df7fc 100644
--- a/docs/syscalls/fifo_create.md
+++ b/docs/syscalls/fifo_create.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**fifo_create**() creates a fifo, which is actually a pair of fifos
+`zx_fifo_create()` creates a fifo, which is actually a pair of fifos
of *elem_count* entries of *elem_size* bytes. Two endpoints are
returned. Writing to one endpoint enqueues an element into the fifo
that the opposing endpoint reads from.
@@ -45,7 +45,7 @@
## RETURN VALUE
-**fifo_create**() returns **ZX_OK** on success. In the event of
+`zx_fifo_create()` returns **ZX_OK** on success. In the event of
failure, one of the following values is returned.
## ERRORS
diff --git a/docs/syscalls/fifo_read.md b/docs/syscalls/fifo_read.md
index edce806..ac4d789 100644
--- a/docs/syscalls/fifo_read.md
+++ b/docs/syscalls/fifo_read.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**fifo_read**() attempts to read up to *count* elements from the fifo
+`zx_fifo_read()` attempts to read up to *count* elements from the fifo
*handle* into *data*.
Fewer elements may be read than requested if there are insufficient
@@ -30,12 +30,12 @@
elements actually read is returned via *actual_count*.
The element size specified by *elem_size* must match the element size
-that was passed into **fifo_create**().
+that was passed into [`zx_fifo_create()`].
*data* must have a size of at least *count * elem_size* bytes.
*actual_count* is allowed to be NULL. This is useful when reading
-a single element: if *count* is 1 and **fifo_read**() returns **ZX_OK**,
+a single element: if *count* is 1 and `zx_fifo_read()` returns **ZX_OK**,
*actual_count* is guaranteed to be 1 and thus can be safely ignored.
It is not legal to read zero elements.
@@ -48,7 +48,7 @@
## RETURN VALUE
-**fifo_read**() returns **ZX_OK** on success, and returns
+`zx_fifo_read()` returns **ZX_OK** on success, and returns
the number of elements read (at least one) via *actual_count*.
## ERRORS
@@ -74,3 +74,7 @@
[fifo_create](fifo_create.md),
[fifo_write](fifo_write.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_fifo_create()`]: fifo_create.md
diff --git a/docs/syscalls/fifo_write.md b/docs/syscalls/fifo_write.md
index 885369a..bb345c5 100644
--- a/docs/syscalls/fifo_write.md
+++ b/docs/syscalls/fifo_write.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**fifo_write**() attempts to write up to *count* elements
+`zx_fifo_write()` attempts to write up to *count* elements
(*count * elem_size* bytes) from *data* to the fifo specified by *handle*.
Fewer elements may be written than requested if there is insufficient
@@ -30,10 +30,10 @@
elements actually written is returned via *actual_count*.
The element size specified by *elem_size* must match the element size
-that was passed into **fifo_create**().
+that was passed into [`zx_fifo_create()`].
*actual_count* is allowed to be NULL. This is useful when writing
-a single element: if *count* is 1 and **fifo_write**() returns **ZX_OK**,
+a single element: if *count* is 1 and `zx_fifo_write()` returns **ZX_OK**,
*actual_count* is guaranteed to be 1 and thus can be safely ignored.
It is not legal to write zero elements.
@@ -46,7 +46,7 @@
## RETURN VALUE
-**fifo_write**() returns **ZX_OK** on success, and returns
+`zx_fifo_write()` returns **ZX_OK** on success, and returns
the number of elements written (at least one) via *actual_count*.
## ERRORS
@@ -72,3 +72,7 @@
[fifo_create](fifo_create.md),
[fifo_read](fifo_read.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_fifo_create()`]: fifo_create.md
diff --git a/docs/syscalls/futex_get_owner.md b/docs/syscalls/futex_get_owner.md
index b4d9e96..16ef0a3 100644
--- a/docs/syscalls/futex_get_owner.md
+++ b/docs/syscalls/futex_get_owner.md
@@ -34,7 +34,7 @@
## RETURN VALUE
-**futex_get_owner**() returns **ZX_OK** on success, and koids hold the owner of
+`zx_futex_get_owner()` returns **ZX_OK** on success, and koids hold the owner of
the futex at the time of the syscall, or **ZX_KOID_INVALID** if there was no
owner.
diff --git a/docs/syscalls/futex_requeue.md b/docs/syscalls/futex_requeue.md
index 8bcfa4f..4521a71 100644
--- a/docs/syscalls/futex_requeue.md
+++ b/docs/syscalls/futex_requeue.md
@@ -44,17 +44,17 @@
### Effects on the _wake futex_ target
-A successful call to **futex_requeue**() results in the owner of the futex being
+A successful call to `zx_futex_requeue()` results in the owner of the futex being
set to nothing, regardless of the wake count. In order to transfer ownership of
-a futex, use the **futex_requeue_single_owner**() variant instead.
-**futex_requeue_single_owner**() will attempt to wake exactly one thread from the
+a futex, use the [`zx_futex_requeue_single_owner()`] variant instead.
+[`zx_futex_requeue_single_owner()`] will attempt to wake exactly one thread from the
futex wait queue. If there is at least one thread to wake, the owner of the futex will be
set to the thread which was woken. Otherwise, the futex
will have no owner.
### Effects on the _requeue futex_ target
-A successful call to **futex_requeue**() or **futex_requeue_single_owner**()
+A successful call to `zx_futex_requeue()` or [`zx_futex_requeue_single_owner()`]
results in the owner of the futex being set to the thread referenced by the
`new_requeue_owner` handle, or to nothing if `new_requeue_owner` is
**ZX_HANDLE_INVALID**.
@@ -67,7 +67,7 @@
## RETURN VALUE
-**futex_requeue**() returns **ZX_OK** on success.
+`zx_futex_requeue()` returns **ZX_OK** on success.
## ERRORS
@@ -87,3 +87,7 @@
[futex_requeue_single_owner](futex_requeue_single_owner.md),
[futex_wait](futex_wait.md),
[futex_wake](futex_wake.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_futex_requeue_single_owner()`]: futex_requeue_single_owner.md
diff --git a/docs/syscalls/futex_requeue_single_owner.md b/docs/syscalls/futex_requeue_single_owner.md
index 4773283..cdddc19 100644
--- a/docs/syscalls/futex_requeue_single_owner.md
+++ b/docs/syscalls/futex_requeue_single_owner.md
@@ -32,7 +32,7 @@
## RETURN VALUE
-**futex_requeue_single_owner**() returns **ZX_OK** on success.
+`zx_futex_requeue_single_owner()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/futex_wait.md b/docs/syscalls/futex_wait.md
index 1da93b3..7fae329 100644
--- a/docs/syscalls/futex_wait.md
+++ b/docs/syscalls/futex_wait.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**futex_wait**() atomically verifies that *value_ptr* still contains the value
+`zx_futex_wait()` atomically verifies that *value_ptr* still contains the value
*current_value* and sleeps until the futex is made available by a call to
`zx_futex_wake`. Optionally, the thread can also be woken up after the
*deadline* (with respect to **ZX_CLOCK_MONOTONIC**) passes.
@@ -29,20 +29,20 @@
## SPURIOUS WAKEUPS
A component that uses futexes should be prepared to handle spurious
-wakeups. A spurious wakeup is a situation where **futex_wait**()
+wakeups. A spurious wakeup is a situation where `zx_futex_wait()`
returns successfully even though the component did not wake the waiter
-by calling **futex_wake**().
+by calling [`zx_futex_wake()`].
Zircon's implementation of futexes currently does not generate
spurious wakeups itself. However, commonly-used algorithms that use
futexes can sometimes generate spurious wakeups. For example, the
usual implementation of `mutex_unlock` can potentially produce a
-**futex_wake**() call on a memory location after the location has been
+[`zx_futex_wake()`] call on a memory location after the location has been
freed and reused for unrelated purposes.
## OWNERSHIP
-A successful call to **futex_wait**() results in the owner of the futex being
+A successful call to `zx_futex_wait()` results in the owner of the futex being
set to the thread referenced by the `new_futex_owner` handle, or to nothing if
`new_futex_owner` is **ZX_HANDLE_INVALID**.
@@ -57,7 +57,7 @@
## RETURN VALUE
-**futex_wait**() returns **ZX_OK** on success.
+`zx_futex_wait()` returns **ZX_OK** on success.
## ERRORS
@@ -76,3 +76,7 @@
[futex objects](../objects/futex.md),
[futex_requeue](futex_requeue.md),
[futex_wake](futex_wake.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_futex_wake()`]: futex_wake.md
diff --git a/docs/syscalls/futex_wake.md b/docs/syscalls/futex_wake.md
index 21439a9..45f4db4 100644
--- a/docs/syscalls/futex_wake.md
+++ b/docs/syscalls/futex_wake.md
@@ -26,10 +26,10 @@
## OWNERSHIP
-A successful call to **futex_wake**() results in the owner of the futex being
+A successful call to `zx_futex_wake()` results in the owner of the futex being
set to nothing, regardless of the wake count. In order to transfer ownership of
-a futex, use the **futex_wake_single_owner**() variant instead.
-**futex_wake_single_owner**() will attempt to wake exactly one thread from the
+a futex, use the [`zx_futex_wake_single_owner()`] variant instead.
+[`zx_futex_wake_single_owner()`] will attempt to wake exactly one thread from the
futex wait queue. If there is at least one thread to wake, the owner of the
futex will be set to the thread which was woken. Otherwise, the futex will have
no owner.
@@ -45,7 +45,7 @@
## RETURN VALUE
-**futex_wake**() returns **ZX_OK** on success.
+`zx_futex_wake()` returns **ZX_OK** on success.
## ERRORS
@@ -57,3 +57,7 @@
[futex_requeue](futex_requeue.md),
[futex_wait](futex_wait.md).
[futex_wake_single_owner](futex_wake_single_owner.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_futex_wake_single_owner()`]: futex_wake_single_owner.md
diff --git a/docs/syscalls/futex_wake_handle_close_thread_exit.md b/docs/syscalls/futex_wake_handle_close_thread_exit.md
index 0d9fd74..5dc5b99 100644
--- a/docs/syscalls/futex_wake_handle_close_thread_exit.md
+++ b/docs/syscalls/futex_wake_handle_close_thread_exit.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**futex_wake_handle_close_thread_exit**() does a sequence of four operations:
+`zx_futex_wake_handle_close_thread_exit()` does a sequence of four operations:
1. `atomic_store_explicit(value_ptr, new_value, memory_order_release);`
2. `zx_futex_wake(value_ptr, wake_count);`
3. `zx_handle_close(close_handle);`
@@ -43,7 +43,7 @@
## RETURN VALUE
-**futex_wake_handle_close_thread_exit**() does not return.
+`zx_futex_wake_handle_close_thread_exit()` does not return.
## ERRORS
diff --git a/docs/syscalls/futex_wake_single_owner.md b/docs/syscalls/futex_wake_single_owner.md
index 0ac452c..8cd7220 100644
--- a/docs/syscalls/futex_wake_single_owner.md
+++ b/docs/syscalls/futex_wake_single_owner.md
@@ -28,7 +28,7 @@
## RETURN VALUE
-**futex_wake_single_owner**() returns **ZX_OK** on success.
+`zx_futex_wake_single_owner()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/guest_create.md b/docs/syscalls/guest_create.md
index 1565e1a..f4042fe 100644
--- a/docs/syscalls/guest_create.md
+++ b/docs/syscalls/guest_create.md
@@ -21,15 +21,15 @@
## DESCRIPTION
-**guest_create**() creates a guest, which is a virtual machine that can be run
+`zx_guest_create()` creates a guest, which is a virtual machine that can be run
within the hypervisor, with *vmar_handle* used to represent the physical address
space of the guest.
To create a guest, a *resource* of *ZX_RSRC_KIND_HYPERVISOR* must be supplied.
In order to begin execution within the guest, a VMO should be mapped into
-*vmar_handle* using **vmar_map**(), and a VCPU must be created using
-**vcpu_create**(), and then run using **vcpu_resume**().
+*vmar_handle* using [`zx_vmar_map()`], and a VCPU must be created using
+[`zx_vcpu_create()`], and then run using [`zx_vcpu_resume()`].
Additionally, a VMO should be mapped into *vmar_handle* to provide a guest with
physical memory.
@@ -40,9 +40,9 @@
**ZX_RIGHT_DUPLICATE** — *guest_handle* may be duplicated.
-**ZX_RIGHT_WRITE** — A trap to be may be set using **guest_set_trap**().
+**ZX_RIGHT_WRITE** — A trap to be may be set using [`zx_guest_set_trap()`].
-**ZX_RIGHT_MANAGE_PROCESS** — A VCPU may be created using **vcpu_create**().
+**ZX_RIGHT_MANAGE_PROCESS** — A VCPU may be created using [`zx_vcpu_create()`].
See [vmar_create](vmar_create.md) for the set of rights applied to
*vmar_handle*.
@@ -55,7 +55,7 @@
## RETURN VALUE
-**guest_create**() returns ZX_OK on success. On failure, an error value is
+`zx_guest_create()` returns ZX_OK on success. On failure, an error value is
returned.
## ERRORS
@@ -81,3 +81,10 @@
[vcpu_write_state](vcpu_write_state.md),
[vmar_map](vmar_map.md),
[vmo_create](vmo_create.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_guest_set_trap()`]: guest_set_trap.md
+[`zx_vcpu_create()`]: vcpu_create.md
+[`zx_vcpu_resume()`]: vcpu_resume.md
+[`zx_vmar_map()`]: vmar_map.md
diff --git a/docs/syscalls/guest_set_trap.md b/docs/syscalls/guest_set_trap.md
index 2b61b23..f703f5c 100644
--- a/docs/syscalls/guest_set_trap.md
+++ b/docs/syscalls/guest_set_trap.md
@@ -23,20 +23,20 @@
## DESCRIPTION
-**guest_set_trap**() sets a trap within a guest, which generates a packet when
+`zx_guest_set_trap()` sets a trap within a guest, which generates a packet when
there is an access by a VCPU within the address range defined by *addr* and
*size*, within the address space defined by *kind*.
If *port_handle* is specified, a packet for the trap will be delivered through
*port_handle* each time the trap is triggered, otherwise if *ZX_HANDLE_INVALID*
-is given, a packet will be delivered through **vcpu_resume**(). This provides
+is given, a packet will be delivered through [`zx_vcpu_resume()`]. This provides
control over whether the packet is delivered asynchronously or synchronously.
When *port_handle* is specified, a fixed number of packets are pre-allocated
per trap. If all the packets are exhausted, execution of the VCPU that caused
the trap will be paused. When at least one packet is dequeued, execution of the
-VCPU will resume. To dequeue a packet from *port_handle*, use **port_wait**().
-Multiple threads may use **port_wait**() to dequeue packets, enabling the use
+VCPU will resume. To dequeue a packet from *port_handle*, use [`zx_port_wait()`].
+Multiple threads may use [`zx_port_wait()`] to dequeue packets, enabling the use
of a thread pool to handle traps.
*key* is used to set the key field within *zx_port_packet_t*, and can be used to
@@ -69,7 +69,7 @@
## RETURN VALUE
-**guest_set_trap**() returns ZX_OK on success. On failure, an error value is
+`zx_guest_set_trap()` returns ZX_OK on success. On failure, an error value is
returned.
## ERRORS
@@ -116,3 +116,8 @@
[vcpu_interrupt](vcpu_interrupt.md),
[vcpu_read_state](vcpu_read_state.md),
[vcpu_write_state](vcpu_write_state.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_port_wait()`]: port_wait.md
+[`zx_vcpu_resume()`]: vcpu_resume.md
diff --git a/docs/syscalls/handle_close.md b/docs/syscalls/handle_close.md
index 00f8259..8493759 100644
--- a/docs/syscalls/handle_close.md
+++ b/docs/syscalls/handle_close.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**handle_close**() closes a *handle*, causing the underlying object to be
+`zx_handle_close()` closes a *handle*, causing the underlying object to be
reclaimed by the kernel if no other handles to it exist.
If the *handle* was used in a pending [object_wait_one](object_wait_one.md) or a
@@ -35,7 +35,7 @@
## RETURN VALUE
-**handle_close**() returns **ZX_OK** on success.
+`zx_handle_close()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/handle_close_many.md b/docs/syscalls/handle_close_many.md
index 13c50c1..79336fe 100644
--- a/docs/syscalls/handle_close_many.md
+++ b/docs/syscalls/handle_close_many.md
@@ -19,7 +19,7 @@
## DESCRIPTION
-**handle_close_many**() closes a number of handles, causing each
+`zx_handle_close_many()` closes a number of handles, causing each
underlying object to be reclaimed by the kernel if no other handles to
it exist.
@@ -40,7 +40,7 @@
## RETURN VALUE
-**handle_close_many**() returns **ZX_OK** on success.
+`zx_handle_close_many()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/handle_duplicate.md b/docs/syscalls/handle_duplicate.md
index b91bdaf..4e87d22 100644
--- a/docs/syscalls/handle_duplicate.md
+++ b/docs/syscalls/handle_duplicate.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**handle_duplicate**() creates a duplicate of *handle*, referring
+`zx_handle_duplicate()` creates a duplicate of *handle*, referring
to the same underlying object, with new access rights *rights*.
To duplicate the handle with the same rights use **ZX_RIGHT_SAME_RIGHTS**. If different
@@ -35,7 +35,7 @@
## RETURN VALUE
-**handle_duplicate**() returns ZX_OK and the duplicate handle via *out* on success.
+`zx_handle_duplicate()` returns ZX_OK and the duplicate handle via *out* on success.
## ERRORS
diff --git a/docs/syscalls/handle_replace.md b/docs/syscalls/handle_replace.md
index a003a80..bb03c3b 100644
--- a/docs/syscalls/handle_replace.md
+++ b/docs/syscalls/handle_replace.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**handle_replace**() creates a replacement for *handle*, referring to
+`zx_handle_replace()` creates a replacement for *handle*, referring to
the same underlying object, with new access rights *rights*.
*handle* is always invalidated.
@@ -37,7 +37,7 @@
## RETURN VALUE
-**handle_replace**() returns **ZX_OK** and the replacement handle (via *out*)
+`zx_handle_replace()` returns **ZX_OK** and the replacement handle (via *out*)
on success.
## ERRORS
diff --git a/docs/syscalls/interrupt_ack.md b/docs/syscalls/interrupt_ack.md
index c23e8bb..e6db74a 100644
--- a/docs/syscalls/interrupt_ack.md
+++ b/docs/syscalls/interrupt_ack.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**interrupt_ack**() acknowledges an interrupt object, causing it to be eligible
+`zx_interrupt_ack()` acknowledges an interrupt object, causing it to be eligible
to trigger again (and delivering a packet to the port it is bound to).
If the interrupt object is a physical interrupt, if it is a level interrupt and
@@ -29,8 +29,8 @@
Virtual interrupts behave as edge interrupts.
This syscall only operates on interrupts which are bound to a port. Interrupts
-being waited upon with **interrupt_wait**() do not need to be re-armed with this
-call -- it happens automatically when **interrupt_wait**() is called.
+being waited upon with [`zx_interrupt_wait()`] do not need to be re-armed with this
+call -- it happens automatically when [`zx_interrupt_wait()`] is called.
## RIGHTS
@@ -40,7 +40,7 @@
## RETURN VALUE
-**interrupt_ack**() returns **ZX_OK** on success. In the event
+`zx_interrupt_ack()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
@@ -51,7 +51,7 @@
**ZX_ERR_BAD_STATE** *handle* is not bound to a port.
-**ZX_ERR_CANCELED** **zx_interrupt_destroy**() was called on *handle*.
+**ZX_ERR_CANCELED** [`zx_interrupt_destroy()`] was called on *handle*.
**ZX_ERR_ACCESS_DENIED** *handle* lacks **ZX_RIGHT_WRITE**.
@@ -64,3 +64,8 @@
[interrupt_wait](interrupt_wait.md),
[port_wait](port_wait.md),
[handle_close](handle_close.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_interrupt_destroy()`]: interrupt_destroy.md
+[`zx_interrupt_wait()`]: interrupt_wait.md
diff --git a/docs/syscalls/interrupt_bind.md b/docs/syscalls/interrupt_bind.md
index 3668600..6b28374 100644
--- a/docs/syscalls/interrupt_bind.md
+++ b/docs/syscalls/interrupt_bind.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**interrupt_bind**() binds an interrupt object to a port.
+`zx_interrupt_bind()` binds an interrupt object to a port.
An interrupt object may only be bound to a single port and may only be bound once.
The interrupt can only bind to a port which is created with **ZX_PORT_BIND_TO_INTERRUPT**
@@ -33,7 +33,7 @@
when binding the interrupt will be present in the `key` field of the `zx_port_packet_t`.
Before another packet may be delivered, the bound interrupt must be re-armed using the
-**interrupt_ack**() syscall. This is (in almost all cases) best done after the interrupt
+[`zx_interrupt_ack()`] syscall. This is (in almost all cases) best done after the interrupt
packet has been fully processed. Especially in the case of multiple threads reading
packets from a port, if the processing thread re-arms the interrupt and it has triggered,
a packet will immediately be delivered to a waiting thread.
@@ -51,7 +51,7 @@
## RETURN VALUE
-**interrupt_bind**() returns **ZX_OK** on success. In the event
+`zx_interrupt_bind()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
@@ -60,9 +60,9 @@
**ZX_ERR_WRONG_TYPE** *handle* is not an interrupt object or *port_handle* is not a port object.
-**ZX_ERR_CANCELED** **zx_interrupt_destroy**() was called on *handle*.
+**ZX_ERR_CANCELED** [`zx_interrupt_destroy()`] was called on *handle*.
-**ZX_ERR_BAD_STATE** A thread is waiting on the interrupt using **zx_interrupt_wait**()
+**ZX_ERR_BAD_STATE** A thread is waiting on the interrupt using [`zx_interrupt_wait()`]
**ZX_ERR_ACCESS_DENIED** the *handle* handle lacks **ZX_RIGHT_READ** or the *port_handle* handle
lacks **ZX_RIGHT_WRITE**
@@ -80,3 +80,9 @@
[interrupt_wait](interrupt_wait.md),
[port_wait](port_wait.md),
[handle_close](handle_close.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_interrupt_ack()`]: interrupt_ack.md
+[`zx_interrupt_destroy()`]: interrupt_destroy.md
+[`zx_interrupt_wait()`]: interrupt_wait.md
diff --git a/docs/syscalls/interrupt_bind_vcpu.md b/docs/syscalls/interrupt_bind_vcpu.md
index d0f6eff..6af37e0 100644
--- a/docs/syscalls/interrupt_bind_vcpu.md
+++ b/docs/syscalls/interrupt_bind_vcpu.md
@@ -20,12 +20,12 @@
## DESCRIPTION
-**interrupt_bind_vcpu**() binds an interrupt object to a VCPU. When the
+`zx_interrupt_bind_vcpu()` binds an interrupt object to a VCPU. When the
interrupt object is triggered, the interrupt is redirected to the VCPU, in order
to be processed by a guest with no host intervention.
An interrupt object may be bound to multiple VCPUs, in order to distribute the
-interrupt. Simply invoke **interrupt_bind_vcpu**() with the same *handle*, but
+interrupt. Simply invoke `zx_interrupt_bind_vcpu()` with the same *handle*, but
different *vcpu*s. However, all VCPUs must belong to a single guest.
## RIGHTS
@@ -38,7 +38,7 @@
## RETURN VALUE
-**interrupt_bind_vcpu**() returns *ZX_OK* on success. On failure, an error value
+`zx_interrupt_bind_vcpu()` returns *ZX_OK* on success. On failure, an error value
is returned.
## ERRORS
@@ -48,10 +48,10 @@
**ZX_ERR_WRONG_TYPE** *handle* is not an interrupt object or *vcpu* is not a
VCPU.
-**ZX_ERR_CANCELED** **interrupt_destroy**() was called on *handle*.
+**ZX_ERR_CANCELED** [`zx_interrupt_destroy()`] was called on *handle*.
**ZX_ERR_BAD_STATE** a thread is waiting on the interrupt using
-**interrupt_wait**().
+[`zx_interrupt_wait()`].
**ZX_ERR_ACCESS_DENIED** *handle* lacks *ZX_RIGHT_READ* or *vcpu* lacks
*ZX_RIGHT_WRITE*.
@@ -67,3 +67,8 @@
[guest_create](guest_create.md),
[interrupt_create](interrupt_create.md),
[vcpu_create](vcpu_create.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_interrupt_destroy()`]: interrupt_destroy.md
+[`zx_interrupt_wait()`]: interrupt_wait.md
diff --git a/docs/syscalls/interrupt_create.md b/docs/syscalls/interrupt_create.md
index 0c9d5b0..a357629 100644
--- a/docs/syscalls/interrupt_create.md
+++ b/docs/syscalls/interrupt_create.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**interrupt_create**() creates an interrupt object which represents a physical
+`zx_interrupt_create()` creates an interrupt object which represents a physical
or virtual interrupt.
If *options* is **ZX_INTERRUPT_VIRTUAL**, *src_obj* and *src_num* are ignored and
@@ -37,14 +37,14 @@
The handles will have *ZX_RIGHT_INSPECT*, *ZX_RIGHT_DUPLICATE*, *ZX_RIGHT_TRANSFER*
(allowing them to be sent to another process via channel write), *ZX_RIGHT_READ*,
-*ZX_RIGHT_WRITE* (required for **interrupt_ack**()), *ZX_RIGHT_WAIT* (required for
-**interrupt_wait**(), and *ZX_RIGHT_SIGNAL* (required for **interrupt_trigger**()).
+*ZX_RIGHT_WRITE* (required for [`zx_interrupt_ack()`]), *ZX_RIGHT_WAIT* (required for
+[`zx_interrupt_wait()`], and *ZX_RIGHT_SIGNAL* (required for [`zx_interrupt_trigger()`]).
Interrupts are said to be "triggered" when the underlying physical interrupt occurs
-or when **interrupt_trigger**() is called on a virtual interrupt. A triggered interrupt,
-when bound to a port with **interrupt_bind**(), causes a packet to be delivered to the port.
+or when [`zx_interrupt_trigger()`] is called on a virtual interrupt. A triggered interrupt,
+when bound to a port with [`zx_interrupt_bind()`], causes a packet to be delivered to the port.
-If not bound to a port, an interrupt object may be waited on with **interrupt_wait**().
+If not bound to a port, an interrupt object may be waited on with [`zx_interrupt_wait()`].
Interrupts cannot be waited on with the **object_wait_** family of calls.
@@ -56,7 +56,7 @@
## RETURN VALUE
-**interrupt_create**() returns **ZX_OK** on success. In the event
+`zx_interrupt_create()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
@@ -82,3 +82,10 @@
[interrupt_wait](interrupt_wait.md),
[port_wait](port_wait.md),
[handle_close](handle_close.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_interrupt_ack()`]: interrupt_ack.md
+[`zx_interrupt_bind()`]: interrupt_bind.md
+[`zx_interrupt_trigger()`]: interrupt_trigger.md
+[`zx_interrupt_wait()`]: interrupt_wait.md
diff --git a/docs/syscalls/interrupt_destroy.md b/docs/syscalls/interrupt_destroy.md
index 288bf79..8b3c26e 100644
--- a/docs/syscalls/interrupt_destroy.md
+++ b/docs/syscalls/interrupt_destroy.md
@@ -18,8 +18,8 @@
## DESCRIPTION
-**interrupt_destroy**() "destroys" an interrupt object, putting it in a state
-where any **interrupt_wait**() operations on it will return ZX_ERR_CANCELED,
+`zx_interrupt_destroy()` "destroys" an interrupt object, putting it in a state
+where any [`zx_interrupt_wait()`] operations on it will return ZX_ERR_CANCELED,
and it is unbound from any ports it was bound to.
This provides a clean shut down mechanism. Closing the last handle to the
@@ -28,10 +28,10 @@
If the interrupt object is bound to a port when cancellation happens, if it
has not yet triggered, or it has triggered but the packet has not yet been
-received by a caller of **port_wait**(), success is returned and any packets
+received by a caller of [`zx_port_wait()`], success is returned and any packets
in flight are removed. Otherwise, **ZX_ERR_NOT_FOUND** is returned, indicating
that the packet has been read but the interrupt has not been re-armed by calling
-**zx_interrupt_ack**().
+[`zx_interrupt_ack()`].
## RIGHTS
@@ -41,7 +41,7 @@
## RETURN VALUE
-**interrupt_destroy**() returns **ZX_OK** on success. In the event
+`zx_interrupt_destroy()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
@@ -64,3 +64,9 @@
[interrupt_wait](interrupt_wait.md),
[port_wait](port_wait.md),
[handle_close](handle_close.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_interrupt_ack()`]: interrupt_ack.md
+[`zx_interrupt_wait()`]: interrupt_wait.md
+[`zx_port_wait()`]: port_wait.md
diff --git a/docs/syscalls/interrupt_trigger.md b/docs/syscalls/interrupt_trigger.md
index 8d5085d..fd6dacc 100644
--- a/docs/syscalls/interrupt_trigger.md
+++ b/docs/syscalls/interrupt_trigger.md
@@ -20,9 +20,9 @@
## DESCRIPTION
-**interrupt_trigger**() is used to trigger a virtual interrupt interrupt object,
+`zx_interrupt_trigger()` is used to trigger a virtual interrupt interrupt object,
causing an interrupt message packet to arrive on the bound port, if it is bound
-to a port, or **interrupt_wait**() to return if it is waiting on this interrupt.
+to a port, or [`zx_interrupt_wait()`] to return if it is waiting on this interrupt.
*options* must be zero.
@@ -45,7 +45,7 @@
**ZX_ERR_BAD_STATE** *handle* is not a virtual interrupt.
-**ZX_ERR_CANCELED** **zx_interrupt_destroy**() was called on *handle*.
+**ZX_ERR_CANCELED** [`zx_interrupt_destroy()`] was called on *handle*.
**ZX_ERR_ACCESS_DENIED** *handle* lacks **ZX_RIGHT_SIGNAL**.
@@ -60,3 +60,8 @@
[interrupt_wait](interrupt_wait.md),
[port_wait](port_wait.md),
[handle_close](handle_close.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_interrupt_destroy()`]: interrupt_destroy.md
+[`zx_interrupt_wait()`]: interrupt_wait.md
diff --git a/docs/syscalls/interrupt_wait.md b/docs/syscalls/interrupt_wait.md
index efe6aae..e83957c 100644
--- a/docs/syscalls/interrupt_wait.md
+++ b/docs/syscalls/interrupt_wait.md
@@ -18,14 +18,14 @@
## DESCRIPTION
-**interrupt_wait**() is a blocking syscall which causes the caller to
+`zx_interrupt_wait()` is a blocking syscall which causes the caller to
wait until an interrupt is triggered. It can only be used on interrupt
-objects that have not been bound to a port with **interrupt_bind**()
+objects that have not been bound to a port with [`zx_interrupt_bind()`]
It also, before the waiting begins, will acknowledge the interrupt object,
-as if **zx_interrupt_ack**() were called on it.
+as if [`zx_interrupt_ack()`] were called on it.
-The wait may be aborted with **zx_interrupt_destroy**() or by closing the handle.
+The wait may be aborted with [`zx_interrupt_destroy()`] or by closing the handle.
## RIGHTS
@@ -35,7 +35,7 @@
## RETURN VALUE
-**interrupt_wait**() returns **ZX_OK** on success, and *out_timestamp*, if
+`zx_interrupt_wait()` returns **ZX_OK** on success, and *out_timestamp*, if
non-NULL, returns the timestamp of when the interrupt was triggered (relative
to **ZX_CLOCK_MONOTONIC**)
@@ -49,7 +49,7 @@
**ZX_ERR_ACCESS_DENIED** *handle* lacks **ZX_RIGHT_WAIT**.
-**ZX_ERR_CANCELED** *handle* was closed while waiting or **zx_interrupt_destroy**() was called
+**ZX_ERR_CANCELED** *handle* was closed while waiting or [`zx_interrupt_destroy()`] was called
on it.
**ZX_ERR_INVALID_ARGS** the *out_timestamp* parameter is an invalid pointer.
@@ -63,3 +63,9 @@
[interrupt_trigger](interrupt_trigger.md),
[port_wait](port_wait.md),
[handle_close](handle_close.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_interrupt_ack()`]: interrupt_ack.md
+[`zx_interrupt_bind()`]: interrupt_bind.md
+[`zx_interrupt_destroy()`]: interrupt_destroy.md
diff --git a/docs/syscalls/iommu_create.md b/docs/syscalls/iommu_create.md
index ad5bbd3..8dd16c4 100644
--- a/docs/syscalls/iommu_create.md
+++ b/docs/syscalls/iommu_create.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**iommu_create**() creates a new object in the kernel representing an IOMMU device.
+`zx_iommu_create()` creates a new object in the kernel representing an IOMMU device.
The value of *type* determines the interpretation of *desc*. See below for
details about the values of *type*.
@@ -48,7 +48,7 @@
## RETURN VALUE
-**iommu_create**() returns ZX_OK and a handle to the new IOMMU
+`zx_iommu_create()` returns ZX_OK and a handle to the new IOMMU
(via *out*) on success. In the event of failure, a negative error value
is returned.
diff --git a/docs/syscalls/job_create.md b/docs/syscalls/job_create.md
index d3cc82a..cccc09e 100644
--- a/docs/syscalls/job_create.md
+++ b/docs/syscalls/job_create.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**job_create**() creates a new child [job object](../objects/job.md) given a
+`zx_job_create()` creates a new child [job object](../objects/job.md) given a
parent job.
Upon success a handle for the new job is returned.
@@ -40,7 +40,7 @@
## RETURN VALUE
-**job_create**() returns ZX_OK and a handle to the new job
+`zx_job_create()` returns ZX_OK and a handle to the new job
(via *out*) on success. In the event of failure, a negative error value
is returned.
diff --git a/docs/syscalls/job_set_policy.md b/docs/syscalls/job_set_policy.md
index c0e4094..fb1b162 100644
--- a/docs/syscalls/job_set_policy.md
+++ b/docs/syscalls/job_set_policy.md
@@ -100,7 +100,7 @@
## RETURN VALUE
-**zx_job_set_policy**() returns **ZX_OK** on success. In the event of failure,
+`zx_job_set_policy()` returns **ZX_OK** on success. In the event of failure,
a negative error value is returned.
## NOTES
diff --git a/docs/syscalls/nanosleep.md b/docs/syscalls/nanosleep.md
index c0c1cd0..4655254 100644
--- a/docs/syscalls/nanosleep.md
+++ b/docs/syscalls/nanosleep.md
@@ -18,11 +18,11 @@
## DESCRIPTION
-**nanosleep**() suspends the calling thread execution until *deadline* passes on
+`zx_nanosleep()` suspends the calling thread execution until *deadline* passes on
**ZX_CLOCK_MONOTONIC**. A *deadline* value less than or equal to **0**
immediately yields the thread.
-To sleep for a duration, use [**zx_deadline_after**](deadline_after.md) and the
+To sleep for a duration, use [[`zx_deadline_after()`]](deadline_after.md) and the
**ZX_\<time-unit\>** helpers:
```
@@ -53,7 +53,7 @@
## RETURN VALUE
-**nanosleep**() always returns **ZX_OK**.
+`zx_nanosleep()` always returns **ZX_OK**.
## SEE ALSO
@@ -61,3 +61,7 @@
[xz_timer_create](timer_create.md),
[timer_set](timer_set.md),
[timer_cancel](timer_cancel.md),
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_deadline_after()`]: deadline_after.md
diff --git a/docs/syscalls/object_get_child.md b/docs/syscalls/object_get_child.md
index cb0abce..002f51a 100644
--- a/docs/syscalls/object_get_child.md
+++ b/docs/syscalls/object_get_child.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**zx_object_get_child** attempts to find a child of the object referred to
+`zx_object_get_child()` attempts to find a child of the object referred to
by *handle* which has the kernel object id specified by *koid*. If such an
object exists, and the requested *rights* are not greater than those provided
by the *handle* to the parent, a new handle to the specified child object is
diff --git a/docs/syscalls/object_get_cookie.md b/docs/syscalls/object_get_cookie.md
index 02c0bae..ce5e438 100644
--- a/docs/syscalls/object_get_cookie.md
+++ b/docs/syscalls/object_get_cookie.md
@@ -23,15 +23,15 @@
Some objects (Events, Event pairs, Resources, VMOs) may have a cookie attached,
which is a 64bit opaque value. Initially the cookie is undefined and not readable.
-If the cookie has been set on an object, **zx_object_get_cookie**() may be
+If the cookie has been set on an object, `zx_object_get_cookie()` may be
called, using the same object as *scope* to obtain the cookie.
Event pairs are special. If one side of the pair is closed, the other side's
cookie is invalidated. An invalidated cookie is not get-able or set-able with any scope.
Cookies are useful for objects that will be passed to another process and
-later returned. By setting the cookie with **zx_object_set_cookie**(),
-using a *scope* that is not accessible by other processes, **zx_object_get_cookie**()
+later returned. By setting the cookie with [`zx_object_set_cookie()`],
+using a *scope* that is not accessible by other processes, `zx_object_get_cookie()`
may later be used to verify that a handle is referring to an object that was
"created" by the calling process and simultaneously return an ID or pointer
to local state for that object.
@@ -48,7 +48,7 @@
## RETURN VALUE
-**zx_object_get_cookie**() returns **ZX_OK** and the *cookie* value on success.
+`zx_object_get_cookie()` returns **ZX_OK** and the *cookie* value on success.
In the event of failure, a negative error value is returned.
@@ -66,3 +66,7 @@
## SEE ALSO
[object_set_cookie](object_set_cookie.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_object_set_cookie()`]: object_set_cookie.md
diff --git a/docs/syscalls/object_get_info.md b/docs/syscalls/object_get_info.md
index bf1fb12..739ccdc 100644
--- a/docs/syscalls/object_get_info.md
+++ b/docs/syscalls/object_get_info.md
@@ -23,7 +23,7 @@
## DESCRIPTION
-**object_get_info()** requests information about the provided handle (or the
+`zx_object_get_info()` requests information about the provided handle (or the
object the handle refers to). The *topic* parameter indicates what specific
information is desired.
@@ -715,7 +715,7 @@
## RETURN VALUE
-**zx_object_get_info**() returns **ZX_OK** on success. In the event of
+`zx_object_get_info()` returns **ZX_OK** on success. In the event of
failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/object_get_property.md b/docs/syscalls/object_get_property.md
index 9d36a2c..944eb53 100644
--- a/docs/syscalls/object_get_property.md
+++ b/docs/syscalls/object_get_property.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**zx_object_get_property()** requests the value of a kernel object's property.
+`zx_object_get_property()` requests the value of a kernel object's property.
Getting a property requires **ZX_RIGHT_GET_PROPERTY** rights on the handle.
The *handle* parameter indicates the target kernel object. Different properties
@@ -163,7 +163,7 @@
## RETURN VALUE
-**zx_object_get_property**() returns **ZX_OK** on success. In the event of
+`zx_object_get_property()` returns **ZX_OK** on success. In the event of
failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/object_set_cookie.md b/docs/syscalls/object_set_cookie.md
index 115d6cb..a7e12c6 100644
--- a/docs/syscalls/object_set_cookie.md
+++ b/docs/syscalls/object_set_cookie.md
@@ -23,7 +23,7 @@
which is a 64bit opaque value. Initially the Cookie is undefined and not
readable.
-Once **zx_object_set_cookie**() is called successfully, the cookie is set,
+Once `zx_object_set_cookie()` is called successfully, the cookie is set,
and the Object referenced by the *scope* handle becomes the key necessary
to read the cookie or modify it. The *scope* may never be changed for the
lifetime of the object.
@@ -32,8 +32,8 @@
cookie is invalidated. An invalidated cookie is not get-able or set-able with any scope.
Cookies are useful for objects that will be passed to another process and
-later returned. By setting the cookie with **zx_object_set_cookie**(),
-using a *scope* that is not accessible by other processes, **zx_object_get_cookie**()
+later returned. By setting the cookie with `zx_object_set_cookie()`,
+using a *scope* that is not accessible by other processes, [`zx_object_get_cookie()`]
may later be used to verify that a handle is referring to an object that was
"created" by the calling process and simultaneously return an ID or pointer
to local state for that object.
@@ -50,7 +50,7 @@
## RETURN VALUE
-**zx_object_set_cookie**() returns **ZX_OK** on success. In the event of failure,
+`zx_object_set_cookie()` returns **ZX_OK** on success. In the event of failure,
a negative error value is returned.
@@ -60,10 +60,14 @@
**ZX_ERR_NOT_SUPPORTED** *handle* is not a handle to an object that may have a cookie set.
-**ZX_ERR_ACCESS_DENIED** **zx_object_set_cookie**() was called previously with a different
+**ZX_ERR_ACCESS_DENIED** `zx_object_set_cookie()` was called previously with a different
object as the *scope*, or the cookie has not been set.
## SEE ALSO
[object_get_cookie](object_get_cookie.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_object_get_cookie()`]: object_get_cookie.md
diff --git a/docs/syscalls/object_set_property.md b/docs/syscalls/object_set_property.md
index 0429bd0..1c3f2b7 100644
--- a/docs/syscalls/object_set_property.md
+++ b/docs/syscalls/object_set_property.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**zx_object_set_property()** modifies the value of a kernel object's property.
+`zx_object_set_property()` modifies the value of a kernel object's property.
Setting a property requires **ZX_RIGHT_SET_PROPERTY** rights on the handle.
See [object_get_property()](object_get_property.md) for a full description.
diff --git a/docs/syscalls/object_signal.md b/docs/syscalls/object_signal.md
index 540d503..2102b1a 100644
--- a/docs/syscalls/object_signal.md
+++ b/docs/syscalls/object_signal.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**zx_object_signal**() asserts and deasserts the userspace-accessible signal
+`zx_object_signal()` asserts and deasserts the userspace-accessible signal
bits on an object.
Most of the 32 signals are reserved for system use and are assigned to
@@ -43,7 +43,7 @@
## RETURN VALUE
-**zx_object_signal**() returns **ZX_OK** on success. In the event of failure, a
+`zx_object_signal()` returns **ZX_OK** on success. In the event of failure, a
negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/object_signal_peer.md b/docs/syscalls/object_signal_peer.md
index 3526923..853fa34 100644
--- a/docs/syscalls/object_signal_peer.md
+++ b/docs/syscalls/object_signal_peer.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**zx_object_signal_peer**() asserts and deasserts the userspace-accessible
+`zx_object_signal_peer()` asserts and deasserts the userspace-accessible
signal bits on the object's peer. A object peer is the opposite endpoint of a
*channel*, *socket*, *fifo*, or *eventpair*.
@@ -44,7 +44,7 @@
## RETURN VALUE
-**zx_object_signal_peer**() returns **ZX_OK** on success. In the event of
+`zx_object_signal_peer()` returns **ZX_OK** on success. In the event of
failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/object_wait_async.md b/docs/syscalls/object_wait_async.md
index 2a7c2dc..4d9f83e 100644
--- a/docs/syscalls/object_wait_async.md
+++ b/docs/syscalls/object_wait_async.md
@@ -22,9 +22,9 @@
## DESCRIPTION
-**object_wait_async**() is a non-blocking syscall which causes packets to be
+`zx_object_wait_async()` is a non-blocking syscall which causes packets to be
enqueued on *port* when the specified condition is met.
-Use **port_wait**() to retrieve the packets.
+Use [`zx_port_wait()`] to retrieve the packets.
*handle* points to the object that is to be watched for changes and must be a waitable object.
@@ -32,7 +32,7 @@
In both cases, *signals* indicates which signals on the object specified by *handle*
will cause a packet to be enqueued, and if **any** of those signals are asserted when
-**object_wait_async**() is called, or become asserted afterwards, a packet will be
+`zx_object_wait_async()` is called, or become asserted afterwards, a packet will be
enqueued on *port* containing all of the currently-asserted signals (not just the ones
listed in the *signals* argument).
@@ -45,7 +45,7 @@
queue, the packet's *observed* field is updated to include all of the currently-asserted
signals (without removing the existing signals).
-In either mode, **port_cancel**() will terminate the operation and if a packet was
+In either mode, [`zx_port_cancel()`] will terminate the operation and if a packet was
in the queue on behalf of the operation, that packet will be removed from the queue.
If the handle is closed, the operation will also be terminated, but packets already
@@ -64,7 +64,7 @@
## RETURN VALUE
-**object_wait_async**() returns **ZX_OK** if the subscription succeeded.
+`zx_object_wait_async()` returns **ZX_OK** if the subscription succeeded.
## ERRORS
@@ -95,3 +95,7 @@
[port_queue](port_queue.md),
[port_wait](port_wait.md).
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_port_cancel()`]: port_cancel.md
+[`zx_port_wait()`]: port_wait.md
diff --git a/docs/syscalls/object_wait_many.md b/docs/syscalls/object_wait_many.md
index a1b17cc..72c59b4 100644
--- a/docs/syscalls/object_wait_many.md
+++ b/docs/syscalls/object_wait_many.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**object_wait_many**() is a blocking syscall which causes the caller to
+`zx_object_wait_many()` is a blocking syscall which causes the caller to
wait until either the *deadline* passes or at least one of the specified
signals is asserted by the object to which the associated handle refers.
If an object is already asserting at least one of the specified signals,
@@ -60,7 +60,7 @@
## RETURN VALUE
-**object_wait_many**() returns **ZX_OK** if any of *waitfor* signals were
+`zx_object_wait_many()` returns **ZX_OK** if any of *waitfor* signals were
observed on their respective object before *deadline* passed.
In the event of **ZX_ERR_TIMED_OUT**, *items* may reflect state changes
diff --git a/docs/syscalls/object_wait_one.md b/docs/syscalls/object_wait_one.md
index f8d7fbe..d392f3f 100644
--- a/docs/syscalls/object_wait_one.md
+++ b/docs/syscalls/object_wait_one.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**object_wait_one**() is a blocking syscall which causes the caller to
+`zx_object_wait_one()` is a blocking syscall which causes the caller to
wait until either the *deadline* passes or the object to which *handle* refers
asserts at least one of the specified *signals*. If the object is already
asserting at least one of the specified *signals*, the wait ends immediately.
@@ -46,7 +46,7 @@
## RETURN VALUE
-**object_wait_one**() returns **ZX_OK** if any of *signals* were observed
+`zx_object_wait_one()` returns **ZX_OK** if any of *signals* were observed
on the object before *deadline* passes.
In the event of **ZX_ERR_TIMED_OUT**, *observed* may reflect state changes
diff --git a/docs/syscalls/pmt_unpin.md b/docs/syscalls/pmt_unpin.md
index d5659c7..b8864b9 100644
--- a/docs/syscalls/pmt_unpin.md
+++ b/docs/syscalls/pmt_unpin.md
@@ -18,11 +18,11 @@
## DESCRIPTION
-**pmt_unpin**() unpins pages that were previously pinned by **bti_pin**(),
+`zx_pmt_unpin()` unpins pages that were previously pinned by [`zx_bti_pin()`],
and revokes the access that was granted by the pin call.
Always consumes *handle*. It is invalid to use *handle* afterwards, including
-to call **handle_close**() on it.
+to call [`zx_handle_close()`] on it.
## RIGHTS
@@ -32,7 +32,7 @@
## RETURN VALUE
-On success, **pmt_unpin**() returns *ZX_OK*.
+On success, `zx_pmt_unpin()` returns *ZX_OK*.
In the event of failure, a negative error value is returned.
## ERRORS
@@ -46,3 +46,8 @@
[bti_create](bti_create.md),
[bti_release_quarantine](bti_release_quarantine.md),
[bti_pin](bti_pin.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_bti_pin()`]: bti_pin.md
+[`zx_handle_close()`]: handle_close.md
diff --git a/docs/syscalls/port_cancel.md b/docs/syscalls/port_cancel.md
index c548c1b..4b7cd23 100644
--- a/docs/syscalls/port_cancel.md
+++ b/docs/syscalls/port_cancel.md
@@ -20,8 +20,8 @@
## DESCRIPTION
-**port_cancel**() is a non-blocking syscall which cancels
-pending **object_wait_async**() calls done with *source* and *key*.
+`zx_port_cancel()` is a non-blocking syscall which cancels
+pending [`zx_object_wait_async()`] calls done with *source* and *key*.
When this call succeeds no new packets from the object pointed by
*source* with *key* will be delivered to *handle*, and pending queued
@@ -35,8 +35,8 @@
## RETURN VALUE
-**zx_port_cancel**() returns **ZX_OK** if cancellation succeeded and
-either queued packets were removed or pending **object_wait_async**() were
+`zx_port_cancel()` returns **ZX_OK** if cancellation succeeded and
+either queued packets were removed or pending [`zx_object_wait_async()`] were
canceled.
## ERRORS
@@ -50,8 +50,12 @@
**ZX_ERR_NOT_SUPPORTED** *source* is a handle that cannot be waited on.
**ZX_ERR_NOT_FOUND** if either no pending packets or pending
-**object_wait_async** calls with *source* and *key* were found.
+[`zx_object_wait_async()`] calls with *source* and *key* were found.
## SEE ALSO
[port_wait](port_wait.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_object_wait_async()`]: object_wait_async.md
diff --git a/docs/syscalls/port_create.md b/docs/syscalls/port_create.md
index 0e54346..052c7ab 100644
--- a/docs/syscalls/port_create.md
+++ b/docs/syscalls/port_create.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**port_create**() creates a port: a waitable object that can be used to read
+`zx_port_create()` creates a port: a waitable object that can be used to read
packets queued by kernel or by user-mode.
If you need this port to be bound to an interrupt, pass **ZX_PORT_BIND_TO_INTERRUPT** to *options*,
@@ -41,7 +41,7 @@
## RETURN VALUE
-**port_create**() returns **ZX_OK** and a valid IO port handle via *out* on
+`zx_port_create()` returns **ZX_OK** and a valid IO port handle via *out* on
success. In the event of failure, an error value is returned.
## ERRORS
diff --git a/docs/syscalls/port_queue.md b/docs/syscalls/port_queue.md
index ecbe556..1627f6a 100644
--- a/docs/syscalls/port_queue.md
+++ b/docs/syscalls/port_queue.md
@@ -19,7 +19,7 @@
## DESCRIPTION
-**port_queue**() queues a *packet* to the port specified
+`zx_port_queue()` queues a *packet* to the port specified
by *handle*.
```
@@ -56,7 +56,7 @@
## RETURN VALUE
-**port_queue**() returns **ZX_OK** on successful queue of a packet.
+`zx_port_queue()` returns **ZX_OK** on successful queue of a packet.
## ERRORS
@@ -69,14 +69,18 @@
**ZX_ERR_ACCESS_DENIED** *handle* does not have **ZX_RIGHT_WRITE**.
**ZX_ERR_SHOULD_WAIT** the port has too many pending packets. Once a thread
-has drained some packets a new **port_queue**() call will likely succeed.
+has drained some packets a new `zx_port_queue()` call will likely succeed.
## NOTES
-The queue is drained by calling **port_wait**().
+The queue is drained by calling [`zx_port_wait()`].
## SEE ALSO
[port_create](port_create.md).
[port_wait](port_wait.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_port_wait()`]: port_wait.md
diff --git a/docs/syscalls/port_wait.md b/docs/syscalls/port_wait.md
index e826443..71769a0 100644
--- a/docs/syscalls/port_wait.md
+++ b/docs/syscalls/port_wait.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**port_wait**() is a blocking syscall which causes the caller to wait until at least
+`zx_port_wait()` is a blocking syscall which causes the caller to wait until at least
one packet is available.
Upon return, if successful *packet* will contain the earliest (in FIFO order)
@@ -33,12 +33,12 @@
result in waiting forever. A value in the past will result in an immediate
timeout, unless a packet is already available for reading.
-Unlike **zx_object_wait_one**() and **zx_object_wait_many**() only one
+Unlike [`zx_object_wait_one()`] and [`zx_object_wait_many()`] only one
waiting thread is released (per available packet) which makes ports
amenable to be serviced by thread pools.
-There are two sources of packets: manually queued packets with **port_queue**() and packets
-generated by kernel when objects registered with **object_wait_async**() change state. In both
+There are two sources of packets: manually queued packets with [`zx_port_queue()`] and packets
+generated by kernel when objects registered with [`zx_object_wait_async()`] change state. In both
cases the packet is always of type **zx_port_packet_t**:
```
@@ -59,7 +59,7 @@
};
```
-In the case of packets generated via **port_queue**() *key* is the key in the
+In the case of packets generated via [`zx_port_queue()`] *key* is the key in the
input packet, *type* is set to **ZX_PKT_TYPE_USER** and the union is of type **zx_packet_user_t**.
```
@@ -71,9 +71,9 @@
} zx_packet_user_t;
```
-The caller of **port_queue**() controls all the values in the structure.
+The caller of [`zx_port_queue()`] controls all the values in the structure.
-In the case of packets generated via **object_wait_async**() *key* is the key passed to the
+In the case of packets generated via [`zx_object_wait_async()`] *key* is the key passed to the
syscall, *type* is set to either **ZX_PKT_TYPE_SIGNAL_ONE** or **ZX_PKT_TYPE_SIGNAL_REP**
and the union is of type **zx_packet_signal_t**:
@@ -86,7 +86,7 @@
```
for **ZX_WAIT_ASYNC_ONCE** and **ZX_WAIT_ASYNC_REPEATING**: *trigger* is the signals
-used in the call to **object_wait_async**() and *count* is a per object defined count
+used in the call to [`zx_object_wait_async()`] and *count* is a per object defined count
of pending operations. Use *key* to track what object this packet corresponds to and
therefore match *count* with the operation.
@@ -102,7 +102,7 @@
## RETURN VALUE
-**port_wait**() returns **ZX_OK** on successful packet dequeuing.
+`zx_port_wait()` returns **ZX_OK** on successful packet dequeuing.
## ERRORS
@@ -120,3 +120,10 @@
[port_create](port_create.md).
[port_queue](port_queue.md).
[object_wait_async](object_wait_async.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_object_wait_async()`]: object_wait_async.md
+[`zx_object_wait_many()`]: object_wait_many.md
+[`zx_object_wait_one()`]: object_wait_one.md
+[`zx_port_queue()`]: port_queue.md
diff --git a/docs/syscalls/process_create.md b/docs/syscalls/process_create.md
index 2a00821..a3b6a2b 100644
--- a/docs/syscalls/process_create.md
+++ b/docs/syscalls/process_create.md
@@ -23,7 +23,7 @@
## DESCRIPTION
-**process_create**() creates a new process.
+`zx_process_create()` creates a new process.
Upon success, handles for the new process and the root of its address space
are returned. The thread will not start executing until *process_start()* is
@@ -47,7 +47,7 @@
## RETURN VALUE
-On success, **process_create**() returns **ZX_OK**, a handle to the new process
+On success, `zx_process_create()` returns **ZX_OK**, a handle to the new process
(via *proc_handle*), and a handle to the root of its address space (via
*vmar_handle*). In the event of failure, a negative error value is returned.
diff --git a/docs/syscalls/process_exit.md b/docs/syscalls/process_exit.md
index 8315e9a..cbd9613 100644
--- a/docs/syscalls/process_exit.md
+++ b/docs/syscalls/process_exit.md
@@ -18,9 +18,9 @@
## DESCRIPTION
-The **zx_process_exit** call ends the calling process with the given
+The `zx_process_exit()` call ends the calling process with the given
return code. The return code of a process can be queried via the
-**ZX_INFO_PROCESS** request to **zx_object_get_info**.
+**ZX_INFO_PROCESS** request to [`zx_object_get_info()`].
## RIGHTS
@@ -30,13 +30,17 @@
## RETURN VALUE
-**zx_process_exit** does not return.
+`zx_process_exit()` does not return.
## ERRORS
-**zx_process_exit** cannot fail.
+`zx_process_exit()` cannot fail.
## SEE ALSO
[object_get_info](object_get_info.md),
[process_create](process_create.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_object_get_info()`]: object_get_info.md
diff --git a/docs/syscalls/process_read_memory.md b/docs/syscalls/process_read_memory.md
index 5b65298..9b9f8af 100644
--- a/docs/syscalls/process_read_memory.md
+++ b/docs/syscalls/process_read_memory.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**zx_process_read_memory**() attempts to read memory of the specified process.
+`zx_process_read_memory()` attempts to read memory of the specified process.
This function will eventually be replaced with something vmo-centric.
@@ -46,7 +46,7 @@
## RETURN VALUE
-**zx_process_read_memory**() returns **ZX_OK** on success.
+`zx_process_read_memory()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned, and the number of
bytes written to *buffer* is undefined.
diff --git a/docs/syscalls/process_start.md b/docs/syscalls/process_start.md
index 620ac64..0dd6037 100644
--- a/docs/syscalls/process_start.md
+++ b/docs/syscalls/process_start.md
@@ -23,10 +23,10 @@
## DESCRIPTION
-**process_start**() is similar to **thread_start**(), but is used for the
+`zx_process_start()` is similar to [`zx_thread_start()`], but is used for the
purpose of starting the first thread in a process.
-**process_start**() causes a thread to begin execution at the program
+`zx_process_start()` causes a thread to begin execution at the program
counter specified by *entry* and with the stack pointer set to *stack*.
The arguments *arg1* and *arg2* are arranged to be in the architecture
specific registers used for the first two arguments of a function call
@@ -35,7 +35,7 @@
The first argument (*arg1*) is a handle, which will be transferred from
the process of the caller to the process which is being started, and an
appropriate handle value will be placed in arg1 for the newly started
-thread. If **process_start** returns an error, *arg1* is closed rather
+thread. If `zx_process_start()` returns an error, *arg1* is closed rather
than transferred to the process being started.
## RIGHTS
@@ -50,7 +50,7 @@
## RETURN VALUE
-**process_start**() returns ZX_OK on success.
+`zx_process_start()` returns ZX_OK on success.
In the event of failure, a negative error value is returned.
## ERRORS
@@ -77,3 +77,7 @@
[thread_create](thread_create.md),
[thread_exit](thread_exit.md),
[thread_start](thread_start.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_thread_start()`]: thread_start.md
diff --git a/docs/syscalls/process_write_memory.md b/docs/syscalls/process_write_memory.md
index 47a5208..f73527a 100644
--- a/docs/syscalls/process_write_memory.md
+++ b/docs/syscalls/process_write_memory.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**zx_process_write_memory**() attempts to write memory of the specified process.
+`zx_process_write_memory()` attempts to write memory of the specified process.
This function will eventually be replaced with something vmo-centric.
@@ -46,7 +46,7 @@
## RETURN VALUE
-**zx_process_write_memory**() returns **ZX_OK** on success.
+`zx_process_write_memory()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned, and the number of
bytes written to *buffer* is undefined.
diff --git a/docs/syscalls/resource_create.md b/docs/syscalls/resource_create.md
index d79486d..c83d806 100644
--- a/docs/syscalls/resource_create.md
+++ b/docs/syscalls/resource_create.md
@@ -24,7 +24,7 @@
## DESCRIPTION
-**resource_create**() creates an resource object for use with other DDK
+`zx_resource_create()` creates an resource object for use with other DDK
syscalls. Resources are typically handed out to bus drivers and rarely need to
be interacted with directly by drivers using driver protocols. Resource objects
grant access to an address space range starting at *base* up to but not
@@ -55,14 +55,14 @@
## RETURN VALUE
-**resource_create**() returns **ZX_OK** on success. In the event of failure, a
+`zx_resource_create()` returns **ZX_OK** on success. In the event of failure, a
negative error value is returned.
The returned handle will have **ZX_RIGHT_TRANSFER** (allowing it to be sent to
another process via channel write), **ZX_RIGHT_DUPLICATE** (allowing the handle
to be duplicated), **ZX_RIGHT_INSPECT** (to allow inspection of the object with
[object_get_info](object_get_info.md) and **ZX_RIGHT_WRITE** which is checked by
-**resource_create**() itself.
+`zx_resource_create()` itself.
## RIGHTS
@@ -93,4 +93,3 @@
[handle_close](handle_close.md), [interrupt_create](interrupt_create.md),
[ioports_request](ioports_request.md),
[vmo_create_physical](vmo_create_physical.md)
-
diff --git a/docs/syscalls/smc_call.md b/docs/syscalls/smc_call.md
index 97aa77c..2576102 100644
--- a/docs/syscalls/smc_call.md
+++ b/docs/syscalls/smc_call.md
@@ -21,11 +21,11 @@
## DESCRIPTION
-**smc_call**() makes a Secure Monitor Call (SMC) from user space. It supports the ARM SMC Calling
+`zx_smc_call()` makes a Secure Monitor Call (SMC) from user space. It supports the ARM SMC Calling
Convention using the *zx_smc_parameters_t* input parameter and *zx_smc_result_t* output parameter.
The input *handle* must be a resource object with sufficient privileges in order to be executed.
-The majority of the parameters are opaque from **smc_call** perspective because they are
+The majority of the parameters are opaque from `zx_smc_call()` perspective because they are
dependent upon the *func_id*. The *func_id* informs the Secure Monitor the service and function
to be invoked. The *client_id* is an optional field intended for secure software to track and
index the calling client OS. The *secure_os_id* is an optional field intended for use when there
@@ -44,7 +44,7 @@
## RETURN VALUE
-**smc_call**() returns ZX_OK if *handle* has sufficient privilege. The
+`zx_smc_call()` returns ZX_OK if *handle* has sufficient privilege. The
return value of the smc call is returned via **out_smc_result** on success. In the event of
failure, a negative error value is returned.
diff --git a/docs/syscalls/socket_accept.md b/docs/syscalls/socket_accept.md
index b883588..f51af05 100644
--- a/docs/syscalls/socket_accept.md
+++ b/docs/syscalls/socket_accept.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**socket_accept**() attempts to receive a new socket via an existing socket
+`zx_socket_accept()` attempts to receive a new socket via an existing socket
connection. The signal **ZX_SOCKET_ACCEPT** is asserted when there is a new
socket available.
@@ -30,7 +30,7 @@
## RETURN VALUE
-**socket_accept**() returns **ZX_OK** on success and the received handle
+`zx_socket_accept()` returns **ZX_OK** on success and the received handle
is returned via *out_socket*. In the event of failure, one of the following
values is returned.
diff --git a/docs/syscalls/socket_create.md b/docs/syscalls/socket_create.md
index 0c0af93..452cd70 100644
--- a/docs/syscalls/socket_create.md
+++ b/docs/syscalls/socket_create.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**socket_create**() creates a socket, a connected pair of
+`zx_socket_create()` creates a socket, a connected pair of
bidirectional stream transports, that can move only data, and that
have a maximum capacity.
@@ -33,7 +33,7 @@
socket control plane.
The **ZX_SOCKET_HAS_ACCEPT** flag may be set to enable transfer
-of sockets over this socket via **socket_share**() and **socket_accept**().
+of sockets over this socket via [`zx_socket_share()`] and [`zx_socket_accept()`].
## RIGHTS
@@ -43,7 +43,7 @@
## RETURN VALUE
-**socket_create**() returns **ZX_OK** on success. In the event of
+`zx_socket_create()` returns **ZX_OK** on success. In the event of
failure, one of the following values is returned.
## ERRORS
@@ -66,3 +66,8 @@
[socket_share](socket_share.md),
[socket_shutdown](socket_shutdown.md),
[socket_write](socket_write.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_socket_accept()`]: socket_accept.md
+[`zx_socket_share()`]: socket_share.md
diff --git a/docs/syscalls/socket_read.md b/docs/syscalls/socket_read.md
index 04b45bc..12af72b 100644
--- a/docs/syscalls/socket_read.md
+++ b/docs/syscalls/socket_read.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**socket_read**() attempts to read *buffer_size* bytes into *buffer*. If
+`zx_socket_read()` attempts to read *buffer_size* bytes into *buffer*. If
successful, the number of bytes actually read are return via
*actual*.
@@ -33,7 +33,7 @@
If *buffer* is too small for the datagram, then the read will be
truncated, and any remaining bytes in the datagram will be discarded.
-If *options* is set to **ZX_SOCKET_CONTROL**, then **socket_read**()
+If *options* is set to **ZX_SOCKET_CONTROL**, then `zx_socket_read()`
attempts to read from the socket control plane.
To determine how many bytes are available to read, use the **rx_buf_available**
@@ -48,7 +48,7 @@
## RETURN VALUE
-**socket_read**() returns **ZX_OK** on success, and writes into
+`zx_socket_read()` returns **ZX_OK** on success, and writes into
*actual* (if non-NULL) the exact number of bytes read.
## ERRORS
diff --git a/docs/syscalls/socket_share.md b/docs/syscalls/socket_share.md
index cfcd6d4..3163856 100644
--- a/docs/syscalls/socket_share.md
+++ b/docs/syscalls/socket_share.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**socket_share**() attempts to send a new socket via an existing socket
+`zx_socket_share()` attempts to send a new socket via an existing socket
connection. The signal **ZX_SOCKET_SHARE** is asserted when it is possible
to send a socket.
@@ -36,7 +36,7 @@
## RETURN VALUE
-**socket_share**() returns **ZX_OK** on success. In the event of failure,
+`zx_socket_share()` returns **ZX_OK** on success. In the event of failure,
one of the following values is returned.
## ERRORS
diff --git a/docs/syscalls/socket_shutdown.md b/docs/syscalls/socket_shutdown.md
index 1f133e0..5c3a7d0 100644
--- a/docs/syscalls/socket_shutdown.md
+++ b/docs/syscalls/socket_shutdown.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**socket_shutdown**() attempts to prevent future reads or writes on a socket,
+`zx_socket_shutdown()` attempts to prevent future reads or writes on a socket,
where options can be a combination of **ZX_SOCKET_SHUTDOWN_READ** and
**ZX_SOCKET_SHUTDOWN_WRITE**:
@@ -41,7 +41,7 @@
## RETURN VALUE
-**socket_shutdown**() returns **ZX_OK** on success.
+`zx_socket_shutdown()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/socket_write.md b/docs/syscalls/socket_write.md
index 2c6f895..db7a817 100644
--- a/docs/syscalls/socket_write.md
+++ b/docs/syscalls/socket_write.md
@@ -22,10 +22,10 @@
## DESCRIPTION
-**socket_write**() attempts to write *buffer_size* bytes to the socket specified
+`zx_socket_write()` attempts to write *buffer_size* bytes to the socket specified
by *handle*. The pointer to *bytes* may be NULL if *buffer_size* is zero.
-If **ZX_SOCKET_CONTROL** is passed to *options*, then **socket_write**()
+If **ZX_SOCKET_CONTROL** is passed to *options*, then `zx_socket_write()`
attempts to write into the socket control plane. A write to the control plane is
never short. If the socket control plane has insufficient space for *buffer*, it
writes nothing and returns **ZX_ERR_OUT_OF_RANGE**.
@@ -55,7 +55,7 @@
## RETURN VALUE
-**socket_write**() returns **ZX_OK** on success.
+`zx_socket_write()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/system_get_features.md b/docs/syscalls/system_get_features.md
index bdbeb18..4b8fecd 100644
--- a/docs/syscalls/system_get_features.md
+++ b/docs/syscalls/system_get_features.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**system_get_features**() populates *features* with a bit mask of
+`zx_system_get_features()` populates *features* with a bit mask of
hardware-specific features. *kind* indicates the specific type of features
to retrieve, e.g. *ZX_FEATURE_KIND_CPU*. The supported kinds and the meaning
of individual feature bits is hardware-dependent.
@@ -31,7 +31,7 @@
## RETURN VALUE
-**system_get_features**() returns **ZX_OK** on success.
+`zx_system_get_features()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/system_get_num_cpus.md b/docs/syscalls/system_get_num_cpus.md
index 9ed5594..d1954d3 100644
--- a/docs/syscalls/system_get_num_cpus.md
+++ b/docs/syscalls/system_get_num_cpus.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**system_get_num_cpus**() returns the number of CPUs (logical processors)
+`zx_system_get_num_cpus()` returns the number of CPUs (logical processors)
that exist on the system currently running. This number cannot change
during a run of the system, only at boot time.
@@ -30,11 +30,11 @@
## RETURN VALUE
-**system_get_num_cpus**() returns the number of CPUs.
+`zx_system_get_num_cpus()` returns the number of CPUs.
## ERRORS
-**system_get_num_cpus**() cannot fail.
+`zx_system_get_num_cpus()` cannot fail.
## NOTES
diff --git a/docs/syscalls/system_get_physmem.md b/docs/syscalls/system_get_physmem.md
index b0991c3..8f65324 100644
--- a/docs/syscalls/system_get_physmem.md
+++ b/docs/syscalls/system_get_physmem.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**system_get_physmem**() returns the total size of physical memory on
+`zx_system_get_physmem()` returns the total size of physical memory on
the machine, in bytes.
## RIGHTS
@@ -29,11 +29,11 @@
## RETURN VALUE
-**system_get_physmem**() returns a number in bytes.
+`zx_system_get_physmem()` returns a number in bytes.
## ERRORS
-**system_get_physmem**() cannot fail.
+`zx_system_get_physmem()` cannot fail.
## NOTES
diff --git a/docs/syscalls/system_get_version.md b/docs/syscalls/system_get_version.md
index eff9857..5b965b6 100644
--- a/docs/syscalls/system_get_version.md
+++ b/docs/syscalls/system_get_version.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**system_get_version**() fills in the given character array with a string
+`zx_system_get_version()` fills in the given character array with a string
identifying the version of the Zircon system currently running.
The provided size must be large enough for the complete string
including its null terminator.
@@ -37,7 +37,7 @@
## RETURN VALUE
-**system_get_version**() returns **ZX_OK** on success.
+`zx_system_get_version()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/system_mexec.md b/docs/syscalls/system_mexec.md
index 19136df..e6e3f01 100644
--- a/docs/syscalls/system_mexec.md
+++ b/docs/syscalls/system_mexec.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**zx_system_mexec**() accepts two vmo handles: *kernel_vmo* should contain a
+`zx_system_mexec()` accepts two vmo handles: *kernel_vmo* should contain a
kernel image and *bootimage_vmo* should contain an initrd whose address shall
be passed to the new kernel as a kernel argument.
@@ -45,7 +45,7 @@
## RETURN VALUE
-**zx_system_mexec**() shall not return upon success.
+`zx_system_mexec()` shall not return upon success.
## SEE ALSO
diff --git a/docs/syscalls/system_mexec_payload_get.md b/docs/syscalls/system_mexec_payload_get.md
index 5cb0339..a52e5bb 100644
--- a/docs/syscalls/system_mexec_payload_get.md
+++ b/docs/syscalls/system_mexec_payload_get.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**zx_system_mexec_payload_get**() accepts a resource handle and a
+`zx_system_mexec_payload_get()` accepts a resource handle and a
pointer/length corresponding to an output buffer and fills the buffer with an
incomplete ZBI containing a sequence of entries that should be appended to a
ZBI before passing that image to zx_system_mexec().
@@ -37,7 +37,7 @@
## RETURN VALUE
-**zx_system_mexec_payload_get**() returns ZX_OK on success.
+`zx_system_mexec_payload_get()` returns ZX_OK on success.
## SEE ALSO
diff --git a/docs/syscalls/task_bind_exception_port.md b/docs/syscalls/task_bind_exception_port.md
index 619d006..2ace05f 100644
--- a/docs/syscalls/task_bind_exception_port.md
+++ b/docs/syscalls/task_bind_exception_port.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**task_bind_exception_port**() is used to bind (or unbind) a port to
+`zx_task_bind_exception_port()` is used to bind (or unbind) a port to
the exception port of a job, process, or thread.
*port* is an IO port created by [zx_port_create](port_create.md). The same
@@ -54,7 +54,7 @@
## RETURN VALUE
-**task_bind_exception_port**() returns **ZX_OK** on success.
+`zx_task_bind_exception_port()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/task_kill.md b/docs/syscalls/task_kill.md
index 67876b0..63b9eb8 100644
--- a/docs/syscalls/task_kill.md
+++ b/docs/syscalls/task_kill.md
@@ -37,13 +37,13 @@
## RETURN VALUE
-On success, **zx_task_kill**() returns **ZX_OK**. If a process or thread uses
+On success, `zx_task_kill()` returns **ZX_OK**. If a process or thread uses
this syscall to kill itself, this syscall does not return.
## NOTES
When using this syscall on a process, the return code for the process
-is -1 as reported by **object_get_info**() via the ZX_INFO_PROCESS topic.
+is -1 as reported by [`zx_object_get_info()`] via the ZX_INFO_PROCESS topic.
## ERRORS
@@ -58,3 +58,7 @@
[job_create](job_create.md),
[process_create](process_create.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_object_get_info()`]: object_get_info.md
diff --git a/docs/syscalls/task_resume_from_exception.md b/docs/syscalls/task_resume_from_exception.md
index 4d63813..3dad171 100644
--- a/docs/syscalls/task_resume_from_exception.md
+++ b/docs/syscalls/task_resume_from_exception.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**task_resume_from_exception**() causes the requested task to resume after an
+`zx_task_resume_from_exception()` causes the requested task to resume after an
exception has been reported to the debug exception port. The port parameter
should identify the [exception port](task_bind_exception_port.md) to which the
exception being resumed from was delivered.
@@ -59,7 +59,7 @@
## RETURN VALUE
-**task_resume_from_exception**() returns **ZX_OK** on success.
+`zx_task_resume_from_exception()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/task_suspend.md b/docs/syscalls/task_suspend.md
index cf75818..1b9d407 100644
--- a/docs/syscalls/task_suspend.md
+++ b/docs/syscalls/task_suspend.md
@@ -18,10 +18,10 @@
## DESCRIPTION
-**task_suspend**() causes the requested task to suspend
+`zx_task_suspend()` causes the requested task to suspend
execution. Task suspension is not synchronous and the task might not
be suspended before the call returns. The task will be suspended soon
-after **task_suspend**() is invoked, unless it is currently blocked in
+after `zx_task_suspend()` is invoked, unless it is currently blocked in
the kernel, in which case it will suspend after being unblocked.
Tasks can be suspended and/or resumed before they are started. If a task is
@@ -29,7 +29,7 @@
Similarly, starting a new thread on a suspended process will suspend the thread
before it executes any code.
-Invoking **task_kill**() on a task that is suspended will successfully kill
+Invoking [`zx_task_kill()`] on a task that is suspended will successfully kill
the task.
## RESUMING
@@ -64,7 +64,7 @@
## RETURN VALUE
-**task_suspend**() returns **ZX_OK** on success.
+`zx_task_suspend()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned.
## ERRORS
@@ -82,3 +82,7 @@
## LIMITATIONS
Currently only thread and process handles are supported.
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_task_kill()`]: task_kill.md
diff --git a/docs/syscalls/task_suspend_token.md b/docs/syscalls/task_suspend_token.md
index c42804f..680446f 100644
--- a/docs/syscalls/task_suspend_token.md
+++ b/docs/syscalls/task_suspend_token.md
@@ -1,8 +1,8 @@
# zx_task_suspend_token
This function replaces [task_suspend](task_suspend.md). When all callers are
-updated, **task_suspend** will be deleted and this function will be renamed
-**task_suspend**.
+updated, [`zx_task_suspend()`] will be deleted and this function will be renamed
+[`zx_task_suspend()`].
## NAME
@@ -22,13 +22,13 @@
## DESCRIPTION
-**task_suspend_token**() causes the requested task to suspend execution. Task
+`zx_task_suspend_token()` causes the requested task to suspend execution. Task
suspension is not synchronous and the task might not be suspended before the
-call returns. The task will be suspended soon after **task_suspend_token**() is
+call returns. The task will be suspended soon after `zx_task_suspend_token()` is
invoked, unless it is currently blocked in the kernel, in which case it will
suspend after being unblocked.
-Invoking **task_kill**() on a task that is suspended will successfully kill
+Invoking [`zx_task_kill()`] on a task that is suspended will successfully kill
the task.
## RESUMING
@@ -47,7 +47,7 @@
## RETURN VALUE
-**task_suspend**() returns **ZX_OK** on success.
+[`zx_task_suspend()`] returns **ZX_OK** on success.
In the event of failure, a negative error value is returned.
## ERRORS
@@ -63,3 +63,8 @@
## LIMITATIONS
Currently only thread handles are supported.
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_task_kill()`]: task_kill.md
+[`zx_task_suspend()`]: task_suspend.md
diff --git a/docs/syscalls/thread_create.md b/docs/syscalls/thread_create.md
index d8e387c..9a006d7 100644
--- a/docs/syscalls/thread_create.md
+++ b/docs/syscalls/thread_create.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**thread_create**() creates a thread within the specified process.
+`zx_thread_create()` creates a thread within the specified process.
Upon success a handle for the new thread is returned. The thread
will not start executing until *thread_start()* is called.
@@ -31,7 +31,7 @@
Thread handles may be waited on and will assert the signal
*ZX_THREAD_TERMINATED* when the thread stops executing (due to
-**thread_exit**() being called).
+[`zx_thread_exit()`] being called).
*process* is the controlling [process object](../objects/process.md) for the
new thread, which will become a child of that process.
@@ -46,7 +46,7 @@
## RETURN VALUE
-On success, **thread_create**() returns **ZX_OK** and a handle (via *out*)
+On success, `zx_thread_create()` returns **ZX_OK** and a handle (via *out*)
to the new thread. In the event of failure, a negative error value is
returned.
@@ -74,3 +74,7 @@
[object_wait_many](object_wait_many.md),
[thread_exit](thread_exit.md),
[thread_start](thread_start.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_thread_exit()`]: thread_exit.md
diff --git a/docs/syscalls/thread_exit.md b/docs/syscalls/thread_exit.md
index 325280e..7151479 100644
--- a/docs/syscalls/thread_exit.md
+++ b/docs/syscalls/thread_exit.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**thread_exit**() causes the currently running thread to cease
+`zx_thread_exit()` causes the currently running thread to cease
running and exit.
The signal *ZX_THREAD_TERMINATED* will be asserted on the thread
@@ -33,7 +33,7 @@
## RETURN VALUE
-**thread_exit**() does not return.
+`zx_thread_exit()` does not return.
## SEE ALSO
diff --git a/docs/syscalls/thread_read_state.md b/docs/syscalls/thread_read_state.md
index e7af390..f8040ed 100644
--- a/docs/syscalls/thread_read_state.md
+++ b/docs/syscalls/thread_read_state.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**thread_read_state**() reads one aspect of state of the thread. The thread
+`zx_thread_read_state()` reads one aspect of state of the thread. The thread
state may only be read when the thread is halted for an exception or the thread
is suspended.
@@ -73,7 +73,7 @@
## RETURN VALUE
-**thread_read_state**() returns **ZX_OK** on success.
+`zx_thread_read_state()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/thread_start.md b/docs/syscalls/thread_start.md
index bc24091..1a6a331 100644
--- a/docs/syscalls/thread_start.md
+++ b/docs/syscalls/thread_start.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**thread_start**() causes a thread to begin execution at the program counter
+`zx_thread_start()` causes a thread to begin execution at the program counter
specified by *thread_entry* and with the stack pointer set to *stack*. The
arguments *arg1* and *arg2* are arranged to be in the architecture specific
registers used for the first two arguments of a function call before the thread
@@ -32,11 +32,11 @@
Thread handles may be waited on and will assert the signal
*ZX_THREAD_TERMINATED* when the thread stops executing (due to
-**thread_exit**() being called.
+[`zx_thread_exit()`] being called.
-*thread_entry* shall point to a function that must call **thread_exit**() or
-**futex_wake_handle_close_thread_exit**() or
-**vmar_unmap_handle_close_thread_exit**() before reaching the last instruction.
+*thread_entry* shall point to a function that must call [`zx_thread_exit()`] or
+[`zx_futex_wake_handle_close_thread_exit()`] or
+[`zx_vmar_unmap_handle_close_thread_exit()`] before reaching the last instruction.
Below is an example:
```
@@ -58,7 +58,7 @@
## RETURN VALUE
-**thread_start**() returns ZX_OK on success.
+`zx_thread_start()` returns ZX_OK on success.
In the event of failure, a negative error value is returned.
## ERRORS
@@ -83,3 +83,9 @@
[thread_exit](thread_exit.md),
[futex_wake_handle_close_thread_exit](futex_wake_handle_close_thread_exit.md),
[vmar_unmap_handle_close_thread_exit](vmar_unmap_handle_close_thread_exit.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_futex_wake_handle_close_thread_exit()`]: futex_wake_handle_close_thread_exit.md
+[`zx_thread_exit()`]: thread_exit.md
+[`zx_vmar_unmap_handle_close_thread_exit()`]: vmar_unmap_handle_close_thread_exit.md
diff --git a/docs/syscalls/thread_write_state.md b/docs/syscalls/thread_write_state.md
index f9b03c7..57d3f7b 100644
--- a/docs/syscalls/thread_write_state.md
+++ b/docs/syscalls/thread_write_state.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**thread_write_state**() writes one aspect of state of the thread. The thread
+`zx_thread_write_state()` writes one aspect of state of the thread. The thread
state may only be written when the thread is halted for an exception or the
thread is suspended.
@@ -58,7 +58,7 @@
## RETURN VALUE
-**thread_write_state**() returns **ZX_OK** on success.
+`zx_thread_write_state()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/ticks_get.md b/docs/syscalls/ticks_get.md
index a5cfb45..3337439 100644
--- a/docs/syscalls/ticks_get.md
+++ b/docs/syscalls/ticks_get.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**zx_ticks_get**() returns the number of high-precision timer ticks since boot.
+`zx_ticks_get()` returns the number of high-precision timer ticks since boot.
These ticks may be processor cycles, high speed timer, profiling timer, etc.
They are not guaranteed to continue advancing when the system is asleep.
@@ -31,7 +31,7 @@
## RETURN VALUE
-**zx_ticks_get**() returns the number of high-precision timer ticks since boot.
+`zx_ticks_get()` returns the number of high-precision timer ticks since boot.
## ERRORS
diff --git a/docs/syscalls/ticks_per_second.md b/docs/syscalls/ticks_per_second.md
index ef0a75a..d1453c7 100644
--- a/docs/syscalls/ticks_per_second.md
+++ b/docs/syscalls/ticks_per_second.md
@@ -18,11 +18,11 @@
## DESCRIPTION
-**zx_ticks_per_second**() returns the number of high-precision timer ticks in a
+`zx_ticks_per_second()` returns the number of high-precision timer ticks in a
second.
-This can be used together with **zx_ticks_get**() to calculate the amount of
-time elapsed between two subsequent calls to **zx_ticks_get**().
+This can be used together with [`zx_ticks_get()`] to calculate the amount of
+time elapsed between two subsequent calls to [`zx_ticks_get()`].
This value can vary from boot to boot of a given system. Once booted,
this value is guaranteed not to change.
@@ -35,12 +35,12 @@
## RETURN VALUE
-**zx_ticks_per_second**() returns the number of high-precision timer ticks in a
+`zx_ticks_per_second()` returns the number of high-precision timer ticks in a
second.
## ERRORS
-**zx_ticks_per_second**() does not report any error conditions.
+`zx_ticks_per_second()` does not report any error conditions.
## EXAMPLES
@@ -58,3 +58,7 @@
## SEE ALSO
[ticks_get](ticks_get.md)
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_ticks_get()`]: ticks_get.md
diff --git a/docs/syscalls/timer_cancel.md b/docs/syscalls/timer_cancel.md
index 6d53b75..fb26187 100644
--- a/docs/syscalls/timer_cancel.md
+++ b/docs/syscalls/timer_cancel.md
@@ -18,12 +18,12 @@
## DESCRIPTION
-**zx_timer_cancel**() cancels a pending timer that was started with
-**timer_set**().
+`zx_timer_cancel()` cancels a pending timer that was started with
+[`zx_timer_set()`].
Upon success the pending timer is canceled and the **ZX_TIMER_SIGNALED**
signal is de-asserted. If a new pending timer is immediately needed
-rather than calling **timer_cancel**() first, call **timer_set**()
+rather than calling `zx_timer_cancel()` first, call [`zx_timer_set()`]
with the new deadline.
## RIGHTS
@@ -34,7 +34,7 @@
## RETURN VALUE
-**zx_timer_cancel**() returns **ZX_OK** on success.
+`zx_timer_cancel()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned.
## ERRORS
@@ -45,9 +45,13 @@
## NOTE
-Calling this function before **timer_set**() has no effect.
+Calling this function before [`zx_timer_set()`] has no effect.
## SEE ALSO
[timer_create](timer_create.md),
[timer_set](timer_set.md)
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_timer_set()`]: timer_set.md
diff --git a/docs/syscalls/timer_create.md b/docs/syscalls/timer_create.md
index 65b6d8f..4429ab2 100644
--- a/docs/syscalls/timer_create.md
+++ b/docs/syscalls/timer_create.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**timer_create**() creates a timer, an object that can signal
+`zx_timer_create()` creates a timer, an object that can signal
when a specified point in time has been reached. The only valid
*clock_id* is **ZX_CLOCK_MONOTONIC**.
@@ -50,7 +50,7 @@
## RETURN VALUE
-**timer_create**() returns **ZX_OK** on success. In the event
+`zx_timer_create()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/timer_set.md b/docs/syscalls/timer_set.md
index dcd13eb..5d6cb7a 100644
--- a/docs/syscalls/timer_set.md
+++ b/docs/syscalls/timer_set.md
@@ -20,19 +20,19 @@
## DESCRIPTION
-**zx_timer_set**() starts a one-shot timer that will fire when
-*deadline* passes. If a previous call to **zx_timer_set**() was
+`zx_timer_set()` starts a one-shot timer that will fire when
+*deadline* passes. If a previous call to `zx_timer_set()` was
pending, the previous timer is canceled and
**ZX_TIMER_SIGNALED** is de-asserted as needed.
The *deadline* parameter specifies a deadline with respect to
**ZX_CLOCK_MONOTONIC**. To wait for a relative interval,
-use **zx_deadline_after**() returned value in *deadline*.
+use [`zx_deadline_after()`] returned value in *deadline*.
To fire the timer immediately pass a *deadline* less than or equal to **0**.
When the timer fires it asserts **ZX_TIMER_SIGNALED**. To de-assert this
-signal call **timer_cancel**() or **timer_set**() again.
+signal call [`zx_timer_cancel()`] or `zx_timer_set()` again.
The *slack* parameter specifies a range from *deadline* - *slack* to
*deadline* + *slack* during which the timer is allowed to fire. The system
@@ -54,7 +54,7 @@
## RETURN VALUE
-**zx_timer_set**() returns **ZX_OK** on success.
+`zx_timer_set()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned.
@@ -71,3 +71,8 @@
[timer_create](timer_create.md),
[timer_cancel](timer_cancel.md),
[deadline_after](deadline_after.md)
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_deadline_after()`]: deadline_after.md
+[`zx_timer_cancel()`]: timer_cancel.md
diff --git a/docs/syscalls/vcpu_create.md b/docs/syscalls/vcpu_create.md
index 2da788d..2d949a4 100644
--- a/docs/syscalls/vcpu_create.md
+++ b/docs/syscalls/vcpu_create.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**vcpu_create**() creates a VCPU within a guest, which allows for execution
+`zx_vcpu_create()` creates a VCPU within a guest, which allows for execution
within the virtual machine. One or more VCPUs may be created per guest, where
the number of VCPUs does not need to match the number of physical CPUs on the
machine.
@@ -31,7 +31,7 @@
*out* is bound to the thread that created it, and all syscalls that operate on
it must be called from the same thread, with the exception of
-**vcpu_interrupt**().
+[`zx_vcpu_interrupt()`].
N.B. VCPU is an abbreviation of virtual CPU.
@@ -57,7 +57,7 @@
## RETURN VALUE
-**vcpu_create**() returns ZX_OK on success. On failure, an error value is
+`zx_vcpu_create()` returns ZX_OK on success. On failure, an error value is
returned.
## ERRORS
@@ -84,3 +84,7 @@
[vcpu_interrupt](vcpu_interrupt.md),
[vcpu_read_state](vcpu_read_state.md),
[vcpu_write_state](vcpu_write_state.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_vcpu_interrupt()`]: vcpu_interrupt.md
diff --git a/docs/syscalls/vcpu_interrupt.md b/docs/syscalls/vcpu_interrupt.md
index ac1c118..a67b14e 100644
--- a/docs/syscalls/vcpu_interrupt.md
+++ b/docs/syscalls/vcpu_interrupt.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**vcpu_interrupt**() raises an interrupt of *vector* on *handle*, and may be
+`zx_vcpu_interrupt()` raises an interrupt of *vector* on *handle*, and may be
called from any thread.
## RIGHTS
@@ -29,7 +29,7 @@
## RETURN VALUE
-**vcpu_interrupt**() returns ZX_OK on success. On failure, an error value is
+`zx_vcpu_interrupt()` returns ZX_OK on success. On failure, an error value is
returned.
## ERRORS
diff --git a/docs/syscalls/vcpu_read_state.md b/docs/syscalls/vcpu_read_state.md
index 0c1a718..9c3626f 100644
--- a/docs/syscalls/vcpu_read_state.md
+++ b/docs/syscalls/vcpu_read_state.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**vcpu_read_state**() reads the state of *handle* as specified by *kind* into
+`zx_vcpu_read_state()` reads the state of *handle* as specified by *kind* into
*buffer*. It is only valid to read the state of *handle* when execution has been
paused.
@@ -35,7 +35,7 @@
## RETURN VALUE
-**vcpu_read_state**() returns ZX_OK on success. On failure, an error value is
+`zx_vcpu_read_state()` returns ZX_OK on success. On failure, an error value is
returned.
## ERRORS
diff --git a/docs/syscalls/vcpu_resume.md b/docs/syscalls/vcpu_resume.md
index 85402f8..8947dcf 100644
--- a/docs/syscalls/vcpu_resume.md
+++ b/docs/syscalls/vcpu_resume.md
@@ -19,10 +19,10 @@
## DESCRIPTION
-**vcpu_resume**() begins or resumes execution of *handle*, and blocks until it has
+`zx_vcpu_resume()` begins or resumes execution of *handle*, and blocks until it has
paused execution. On pause of execution, *packet* is populated with reason for
the pause. After handling the reason, execution may be resumed by calling
-**vcpu_resume**() again.
+`zx_vcpu_resume()` again.
N.B. Execution of a *handle* must be resumed on the same thread it was created on.
@@ -34,7 +34,7 @@
## RETURN VALUE
-**vcpu_resume**() returns *ZX_OK* on success. On failure, an error value is
+`zx_vcpu_resume()` returns *ZX_OK* on success. On failure, an error value is
returned.
## ERRORS
diff --git a/docs/syscalls/vcpu_write_state.md b/docs/syscalls/vcpu_write_state.md
index ec27110..43189f0 100644
--- a/docs/syscalls/vcpu_write_state.md
+++ b/docs/syscalls/vcpu_write_state.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**vcpu_write_state**() writes the state of *handle* as specified by *kind* from
+`zx_vcpu_write_state()` writes the state of *handle* as specified by *kind* from
*buffer*. It is only valid to write the state of *handle* when execution has been
paused.
@@ -35,7 +35,7 @@
## RETURN VALUE
-**vcpu_write_state**() returns ZX_OK on success. On failure, an error value is
+`zx_vcpu_write_state()` returns ZX_OK on success. On failure, an error value is
returned.
## ERRORS
diff --git a/docs/syscalls/vmar_allocate.md b/docs/syscalls/vmar_allocate.md
index 4d86a6d..5d0684d 100644
--- a/docs/syscalls/vmar_allocate.md
+++ b/docs/syscalls/vmar_allocate.md
@@ -57,7 +57,7 @@
## RETURN VALUE
-**vmar_allocate**() returns **ZX_OK**, the absolute base address of the
+`zx_vmar_allocate()` returns **ZX_OK**, the absolute base address of the
subregion (via *child_addr*), and a handle to the new subregion (via
*child_vmar*) on success. The base address will be page-aligned and non-zero.
In the event of failure, a negative error value is returned.
@@ -86,7 +86,7 @@
### Deallocation
The address space occupied by a VMAR will remain allocated (within its
-parent VMAR) until the VMAR is destroyed by calling **vmar_destroy**().
+parent VMAR) until the VMAR is destroyed by calling [`zx_vmar_destroy()`].
Note that just closing the VMAR's handle does not deallocate the address
space occupied by the VMAR.
@@ -106,3 +106,7 @@
[vmar_map](vmar_map.md),
[vmar_protect](vmar_protect.md),
[vmar_unmap](vmar_unmap.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_vmar_destroy()`]: vmar_destroy.md
diff --git a/docs/syscalls/vmar_destroy.md b/docs/syscalls/vmar_destroy.md
index 6743a73..4627f52 100644
--- a/docs/syscalls/vmar_destroy.md
+++ b/docs/syscalls/vmar_destroy.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**vmar_destroy**() unmaps all mappings within the given region, and destroys
+`zx_vmar_destroy()` unmaps all mappings within the given region, and destroys
all sub-regions of the region. Note that this operation is logically recursive.
This operation does not close *handle*. Any outstanding handles to this
@@ -32,7 +32,7 @@
## RETURN VALUE
-**vmar_destroy**() returns **ZX_OK** on success.
+`zx_vmar_destroy()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/vmar_map.md b/docs/syscalls/vmar_map.md
index c772b47..4c900c4 100644
--- a/docs/syscalls/vmar_map.md
+++ b/docs/syscalls/vmar_map.md
@@ -72,7 +72,7 @@
## RETURN VALUE
-**vmar_map**() returns **ZX_OK** and the absolute base address of the
+`zx_vmar_map()` returns **ZX_OK** and the absolute base address of the
mapping (via *mapped_addr*) on success. The base address will be page-aligned
and non-zero. In the event of failure, a negative error value is returned.
diff --git a/docs/syscalls/vmar_protect.md b/docs/syscalls/vmar_protect.md
index df753de..a1cbaf0 100644
--- a/docs/syscalls/vmar_protect.md
+++ b/docs/syscalls/vmar_protect.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**vmar_protect**() alters the access protections for the memory mappings
+`zx_vmar_protect()` alters the access protections for the memory mappings
in the range of *len* bytes starting from *addr*. The *options* argument should
be a bitwise-or of one or more of the following:
- **ZX_VM_PERM_READ** Map as readable. It is an error if *handle*
@@ -51,7 +51,7 @@
## RETURN VALUE
-**vmar_protect**() returns **ZX_OK** on success.
+`zx_vmar_protect()` returns **ZX_OK** on success.
## ERRORS
diff --git a/docs/syscalls/vmar_unmap.md b/docs/syscalls/vmar_unmap.md
index 6855203..6e60218 100644
--- a/docs/syscalls/vmar_unmap.md
+++ b/docs/syscalls/vmar_unmap.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**vmar_unmap**() unmaps all VMO mappings and destroys (as if **vmar_destroy**
+`zx_vmar_unmap()` unmaps all VMO mappings and destroys (as if [`zx_vmar_destroy()`]
were called) all sub-regions within the absolute range including *addr* and ending
before exclusively at *addr* + *len*. Any sub-region that is in the range must
be fully in the range (i.e. partial overlaps are an error). If a mapping is
@@ -35,7 +35,7 @@
## RETURN VALUE
-**vmar_unmap**() returns **ZX_OK** on success.
+`zx_vmar_unmap()` returns **ZX_OK** on success.
## ERRORS
@@ -58,3 +58,7 @@
[vmar_destroy](vmar_destroy.md),
[vmar_map](vmar_map.md),
[vmar_protect](vmar_protect.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_vmar_destroy()`]: vmar_destroy.md
diff --git a/docs/syscalls/vmar_unmap_handle_close_thread_exit.md b/docs/syscalls/vmar_unmap_handle_close_thread_exit.md
index e85cfeb..f5c44da 100644
--- a/docs/syscalls/vmar_unmap_handle_close_thread_exit.md
+++ b/docs/syscalls/vmar_unmap_handle_close_thread_exit.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**vmar_unmap_handle_close_thread_exit**() does a sequence of three operations:
+`zx_vmar_unmap_handle_close_thread_exit()` does a sequence of three operations:
1. `zx_vmar_unmap(vmar_handle, addr, size);`
2. `zx_handle_close(close_handle);`
3. `zx_thread_exit();`
@@ -43,7 +43,7 @@
## RETURN VALUE
-**vmar_unmap_handle_close_thread_exit**() does not return on success.
+`zx_vmar_unmap_handle_close_thread_exit()` does not return on success.
## ERRORS
diff --git a/docs/syscalls/vmo_clone.md b/docs/syscalls/vmo_clone.md
index 6f9d4ae..d723626 100644
--- a/docs/syscalls/vmo_clone.md
+++ b/docs/syscalls/vmo_clone.md
@@ -22,7 +22,7 @@
## DESCRIPTION
-**vmo_clone**() creates a new virtual memory object (VMO) that clones a range
+`zx_vmo_clone()` creates a new virtual memory object (VMO) that clones a range
of an existing vmo.
One handle is returned on success, representing an object with the requested
@@ -71,14 +71,14 @@
VMOs produced by this mode will interact with the VMO syscalls in the following
ways:
-- The DECOMMIT and COMMIT modes of **vmo_op_range**() on a clone will only affect pages
+- The DECOMMIT and COMMIT modes of [`zx_vmo_op_range()`] on a clone will only affect pages
allocated to the clone, never its parent.
-- If a page in a clone is decommitted (e.g. with **vmo_op_range**()), the parent's page will
+- If a page in a clone is decommitted (e.g. with [`zx_vmo_op_range()`]), the parent's page will
become visible once again, still with copy-on-write semantics.
-- If a page is committed to a clone using the **vmo_op_range**() COMMIT mode, a
+- If a page is committed to a clone using the [`zx_vmo_op_range()`] COMMIT mode, a
the new page will have the same contents as the parent's corresponding page
(or zero-filled if no such page exists).
-- If the **vmo_op_range**() LOOKUP mode is used, the parent's pages will be visible
+- If the [`zx_vmo_op_range()`] LOOKUP mode is used, the parent's pages will be visible
where the clone has not modified them.
## RIGHTS
@@ -89,7 +89,7 @@
## RETURN VALUE
-**vmo_clone**() returns **ZX_OK** on success. In the event
+`zx_vmo_clone()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
@@ -116,3 +116,7 @@
[vmo_get_size](vmo_get_size.md),
[vmo_op_range](vmo_op_range.md),
[vmar_map](vmar_map.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_vmo_op_range()`]: vmo_op_range.md
diff --git a/docs/syscalls/vmo_create.md b/docs/syscalls/vmo_create.md
index c972eea..a713bb7 100644
--- a/docs/syscalls/vmo_create.md
+++ b/docs/syscalls/vmo_create.md
@@ -18,12 +18,12 @@
## DESCRIPTION
-**vmo_create**() creates a new virtual memory object (VMO), which represents
+`zx_vmo_create()` creates a new virtual memory object (VMO), which represents
a container of zero to *size* bytes of memory managed by the operating
system.
The size of the VMO will be rounded up to the next page size boundary.
-Use **vmo_get_size**() to return the current size of the VMO.
+Use [`zx_vmo_get_size()`] to return the current size of the VMO.
One handle is returned on success, representing an object with the requested
size.
@@ -64,7 +64,7 @@
## RETURN VALUE
-**vmo_create**() returns **ZX_OK** on success. In the event
+`zx_vmo_create()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
@@ -85,3 +85,7 @@
[vmo_get_size](vmo_get_size.md),
[vmo_op_range](vmo_op_range.md),
[vmar_map](vmar_map.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_vmo_get_size()`]: vmo_get_size.md
diff --git a/docs/syscalls/vmo_create_physical.md b/docs/syscalls/vmo_create_physical.md
index 1054c83..93c807c 100644
--- a/docs/syscalls/vmo_create_physical.md
+++ b/docs/syscalls/vmo_create_physical.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**vmo_create_physical**() creates a new virtual memory object (VMO), which represents the
+`zx_vmo_create_physical()` creates a new virtual memory object (VMO), which represents the
*size* bytes of physical memory beginning at physical address *paddr*.
One handle is returned on success, representing an object with the requested
@@ -54,8 +54,8 @@
## NOTES
-The VMOs created by this syscall are not usable with **vmo_read**() and
-**vmo_write**().
+The VMOs created by this syscall are not usable with [`zx_vmo_read()`] and
+[`zx_vmo_write()`].
## RIGHTS
@@ -65,7 +65,7 @@
## RETURN VALUE
-**vmo_create_physical**() returns **ZX_OK** on success. In the event
+`zx_vmo_create_physical()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
@@ -85,3 +85,8 @@
## SEE ALSO
[vmar_map](vmar_map.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_vmo_read()`]: vmo_read.md
+[`zx_vmo_write()`]: vmo_write.md
diff --git a/docs/syscalls/vmo_get_size.md b/docs/syscalls/vmo_get_size.md
index 1a98260..8669f33 100644
--- a/docs/syscalls/vmo_get_size.md
+++ b/docs/syscalls/vmo_get_size.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**vmo_get_size**() returns the current size of the VMO.
+`zx_vmo_get_size()` returns the current size of the VMO.
## RIGHTS
@@ -28,7 +28,7 @@
## RETURN VALUE
-**vmo_get_size**() returns **ZX_OK** on success. In the event
+`zx_vmo_get_size()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/vmo_op_range.md b/docs/syscalls/vmo_op_range.md
index 1ef0032..89a78f0 100644
--- a/docs/syscalls/vmo_op_range.md
+++ b/docs/syscalls/vmo_op_range.md
@@ -23,7 +23,7 @@
## DESCRIPTION
-**vmo_op_range()** performs cache and memory operations against pages held by the VMO.
+`zx_vmo_op_range()` performs cache and memory operations against pages held by the VMO.
*offset* byte offset specifying the starting location for *op* in the VMO's held memory.
@@ -75,7 +75,7 @@
## RETURN VALUE
-**vmo_op_range**() returns **ZX_OK** on success. In the event of failure, a negative error
+`zx_vmo_op_range()` returns **ZX_OK** on success. In the event of failure, a negative error
value is returned.
## ERRORS
diff --git a/docs/syscalls/vmo_read.md b/docs/syscalls/vmo_read.md
index af05553..feab4a9 100644
--- a/docs/syscalls/vmo_read.md
+++ b/docs/syscalls/vmo_read.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**vmo_read**() attempts to read exactly *buffer_size* bytes from a VMO at *offset*.
+`zx_vmo_read()` attempts to read exactly *buffer_size* bytes from a VMO at *offset*.
*buffer* pointer to a user buffer to read bytes into.
@@ -36,7 +36,7 @@
## RETURN VALUE
-**zx_vmo_read**() returns **ZX_OK** on success, and exactly *buffer_size* bytes will
+`zx_vmo_read()` returns **ZX_OK** on success, and exactly *buffer_size* bytes will
have been written to *buffer*.
In the event of failure, a negative error value is returned, and the number of
bytes written to *buffer* is undefined.
diff --git a/docs/syscalls/vmo_replace_as_executable.md b/docs/syscalls/vmo_replace_as_executable.md
index d436c52..d019edc 100644
--- a/docs/syscalls/vmo_replace_as_executable.md
+++ b/docs/syscalls/vmo_replace_as_executable.md
@@ -20,7 +20,7 @@
## DESCRIPTION
-**vmo_replace_as_executable**() creates a replacement for *handle*, referring
+`zx_vmo_replace_as_executable()` creates a replacement for *handle*, referring
to the same underlying VM object, adding the right **ZX_RIGHT_EXECUTE**.
*handle* is always invalidated.
@@ -38,7 +38,7 @@
## RETURN VALUE
-**vmo_replace_as_executable**() returns **ZX_OK** on success. In the event
+`zx_vmo_replace_as_executable()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/vmo_set_cache_policy.md b/docs/syscalls/vmo_set_cache_policy.md
index 73f0063..e1cbf14 100644
--- a/docs/syscalls/vmo_set_cache_policy.md
+++ b/docs/syscalls/vmo_set_cache_policy.md
@@ -18,7 +18,7 @@
## DESCRIPTION
-**vmo_set_cache_policy()** sets caching policy for a VMO. Generally used on VMOs
+`zx_vmo_set_cache_policy()` sets caching policy for a VMO. Generally used on VMOs
that point directly at physical memory. Such VMOs are generally only handed to
userspace via bus protocol interfaces, so this syscall will typically only be
used by drivers dealing with device memory. This call can also be used on a
@@ -48,7 +48,7 @@
## RETURN VALUE
-**vmo_set_cache_policy()** returns **ZX_OK** on success. In the event of
+`zx_vmo_set_cache_policy()` returns **ZX_OK** on success. In the event of
failure, a negative error value is returned.
## ERRORS
diff --git a/docs/syscalls/vmo_set_size.md b/docs/syscalls/vmo_set_size.md
index 2c6dacc..ef13b69 100644
--- a/docs/syscalls/vmo_set_size.md
+++ b/docs/syscalls/vmo_set_size.md
@@ -18,10 +18,10 @@
## DESCRIPTION
-**vmo_set_size**() sets the new size of a VMO object.
+`zx_vmo_set_size()` sets the new size of a VMO object.
The size will be rounded up to the next page size boundary.
-Subsequent calls to **vmo_get_size**() will return the rounded up size.
+Subsequent calls to [`zx_vmo_get_size()`] will return the rounded up size.
## RIGHTS
@@ -31,7 +31,7 @@
## RETURN VALUE
-**vmo_set_size**() returns **ZX_OK** on success. In the event
+`zx_vmo_set_size()` returns **ZX_OK** on success. In the event
of failure, a negative error value is returned.
## ERRORS
@@ -56,3 +56,7 @@
[vmo_write](vmo_write.md),
[vmo_get_size](vmo_get_size.md),
[vmo_op_range](vmo_op_range.md).
+
+<!-- References updated by update-docs-from-abigen, do not edit. -->
+
+[`zx_vmo_get_size()`]: vmo_get_size.md
diff --git a/docs/syscalls/vmo_write.md b/docs/syscalls/vmo_write.md
index 6229e11..44cd704 100644
--- a/docs/syscalls/vmo_write.md
+++ b/docs/syscalls/vmo_write.md
@@ -21,7 +21,7 @@
## DESCRIPTION
-**vmo_write**() attempts to write exactly *buffer_size* bytes to a VMO at *offset*.
+`zx_vmo_write()` attempts to write exactly *buffer_size* bytes to a VMO at *offset*.
*buffer* pointer to a user buffer to write bytes from.
@@ -35,7 +35,7 @@
## RETURN VALUE
-**zx_vmo_write**() returns **ZX_OK** on success, and exactly *buffer_size* bytes will
+`zx_vmo_write()` returns **ZX_OK** on success, and exactly *buffer_size* bytes will
have been written from *buffer*.
In the event of failure, a negative error value is returned, and the number of
bytes written from *buffer* is undefined.
diff --git a/scripts/update-docs-from-abigen b/scripts/update-docs-from-abigen
index 8f3320a..bdb5bd9 100755
--- a/scripts/update-docs-from-abigen
+++ b/scripts/update-docs-from-abigen
@@ -13,13 +13,14 @@
of what it does). So it should be run manually after updating syscalls.abigen
and building zircon, followed by uploading the changes to docs/ as a CL.
-Currently, it only updates the rights annotations, but in the future it should
-update the signature, arguments, etc. too.
+It updates the signature, synopsis, and rights annotations, and corrects some
+formatting.
"""
import argparse
import json
import os
+import re
import subprocess
import sys
@@ -29,6 +30,9 @@
'', '<!-- Updated by update-docs-from-abigen, do not edit. -->', ''
]
+REFERENCES_COMMENT = \
+ '<!-- References updated by update-docs-from-abigen, do not edit. -->'
+
def parse_args():
parser = argparse.ArgumentParser(
@@ -50,6 +54,7 @@
default=False,
action="store_true",
help='if set, generate stubs for any syscalls that are missing')
+ parser.add_argument('name', nargs='*', help='only generate these syscalls')
return parser.parse_args()
@@ -93,8 +98,8 @@
'.'
],
[
- 'ARG', 'must', 'be', 'of', 'type', 'TYPE1', 'or', 'TYPE2', 'and', 'have', 'RIGHT',
- '.'
+ 'ARG', 'must', 'be', 'of', 'type', 'TYPE1', 'or', 'TYPE2', 'and',
+ 'have', 'RIGHT', '.'
],
[
'If', 'ARG1', 'is', 'VALUE', ',', 'ARG2', 'must', 'have', 'RIGHT',
@@ -459,6 +464,57 @@
return orphan_count
+SYSCALL_RE = {}
+
+
+def update_syscall_references(lines, syscall, all_syscall_names, warn):
+ """Attempts to update all syscall references to a canonical format, and
+ linkifies them to their corresponding syscall.
+
+ TODO(ZX-3106): It'd be nice to do the references from outside of
+ docs/syscalls/ into syscalls too, in a similar style.
+ """
+
+ text = '\n'.join(lines)
+
+ # Precompile these regexes as it takes measurable time.
+ if not SYSCALL_RE:
+ for sc in all_syscall_names:
+ # Look for **zx_stuff()** and [`zx_stuff()`], with both "zx_" and
+ # the () being optional.
+ SYSCALL_RE[sc] = re.compile(
+ r'\*{2}(?:zx_)?' + sc + r'(?:\(\))?\*{2}(?:\(\))?'
+ r'|'
+ r'(?:\[)`(?:zx_)?' + sc + r'(?:\(\))?`(?:\])?(\(\))?')
+
+ referred_to = set()
+ for sc in all_syscall_names:
+ scre = SYSCALL_RE[sc]
+ self = sc == syscall['name']
+ repl = '`zx_' + sc + '()`'
+ # Don't link to ourselves.
+ if not self:
+ repl = '[' + repl + ']'
+ text, count = scre.subn(repl, text)
+ if count and not self:
+ referred_to.add(sc)
+
+ lines[:] = text.splitlines()
+
+ if REFERENCES_COMMENT not in lines:
+ lines.extend(['', REFERENCES_COMMENT])
+ start_index = lines.index(REFERENCES_COMMENT)
+
+ references = []
+ for ref in sorted(referred_to):
+ references.append('[`zx_' + ref + '()`]: ' + ref + '.md')
+ lines[start_index:] = [REFERENCES_COMMENT, ''] + references
+
+ # Drop references section if it's empty to not be noisy.
+ if lines[-3:] == ['', REFERENCES_COMMENT, '']:
+ lines[:] = lines[:-3]
+
+
def main():
args = parse_args()
inf = os.path.relpath(args.json)
@@ -466,8 +522,11 @@
print 'using %s as input and updating %s...' % (inf, outf)
data = json.loads(open(inf, 'rb').read())
missing_count = 0
+ all_syscall_names = set(x['name'] for x in data['syscalls'])
for syscall in data['syscalls']:
name = syscall['name']
+ if args.name and name not in args.name:
+ continue
md = os.path.join(outf, name + '.md')
if not os.path.exists(md) and args.generate_missing:
@@ -490,6 +549,7 @@
update_name(lines, syscall, warn)
update_synopsis(lines, syscall, warn)
update_rights(lines, syscall, warn)
+ update_syscall_references(lines, syscall, all_syscall_names, warn)
with open(md, 'wb') as f:
f.write('\n'.join(lines) + '\n')
