[docs] Improve object docs.
This brings the object docs in line with the newer syscall docs.
TEST: visual inspection.
Change-Id: Ia4911a48adcff1c7c7ab65777638a45479981722
diff --git a/docs/objects/bus_transaction_initiator.md b/docs/objects/bus_transaction_initiator.md
index 72cc00a..598648a 100644
--- a/docs/objects/bus_transaction_initiator.md
+++ b/docs/objects/bus_transaction_initiator.md
@@ -24,22 +24,27 @@
may fail and the issuing device may need a reset in order to continue functioning.
A BTI manages a list of quarantined PMTs. If a PMT was created from a BTI using
-**bti_pin**(), and the PMT's handle is released without **pmt_unpin**() being
+[`zx_bti_pin()`], and the PMT's handle is released without [`zx_pmt_unpin()`] being
called, the PMT will be quarantined. Quarantined PMTs will prevent their
underlying physical memory from being released to the system for reuse, in order
to prevent DMA to memory that has since been reallocated. The quarantine may be
-cleared by invoking **bti_release_quarantine**().
+cleared by invoking [`zx_bti_release_quarantine()`].
TODO(teisenbe): Add details about failed transaction notification.
## SEE ALSO
-+ [pmt](pinned_memory_token.md) - Pinned Memory Tokens
-+ [vm_object](vm_object.md) - Virtual Memory Objects
+ - [pmt](pinned_memory_token.md) - Pinned Memory Tokens
+ - [vm_object](vm_object.md) - Virtual Memory Objects
## SYSCALLS
-+ [bti_create](../syscalls/bti_create.md) - create a new bus transaction initiator
-+ [bti_pin](../syscalls/bti_pin.md) - pin memory and grant access to it to the BTI
-+ [bti_release_quarantine](../syscalls/bti_release_quarantine.md) - release quarantined PMTs
-+ [pmt_unpin](../syscalls/pmt_unpin.md) - revoke access and unpin memory
+ - [`zx_bti_create()`] - create a new bus transaction initiator
+ - [`zx_bti_pin()`] - pin memory and grant access to it to the BTI
+ - [`zx_bti_release_quarantine()`] - release quarantined PMTs
+ - [`zx_pmt_unpin()`] - revoke access and unpin memory
+
+[`zx_bti_create()`]: ../syscalls/bti_create.md)
+[`zx_bti_pin()`]: ../syscalls/bti_pin.md
+[`zx_bti_release_quarantine()`]: ../syscalls/bti_release_quarantine.md
+[`zx_pmt_unpin()`]: ../syscalls/pmt_unpin.md
diff --git a/docs/objects/channel.md b/docs/objects/channel.md
index ae993d3..42889c1 100644
--- a/docs/objects/channel.md
+++ b/docs/objects/channel.md
@@ -13,17 +13,17 @@
Channels maintain an ordered queue of messages to be delivered in either
direction. A message consists of some amount of data and some number of handles.
-A call to *zx_channel_write()* enqueues one message, and a call to
-*zx_channel_read()* dequeues one message (if any are queued). A thread can block
-until messages are pending via *zx_object_wait_one()* or other waiting
+A call to [`zx_channel_write()`] enqueues one message, and a call to
+[`zx_channel_read()`] dequeues one message (if any are queued). A thread can block
+until messages are pending via [`zx_object_wait_one()`] or other waiting
mechanisms.
-Alternatively, a call to *zx_channel_call()* enqueues a message in one
+Alternatively, a call to [`zx_channel_call()`] enqueues a message in one
direction of the channel, waits for a corresponding response, and
dequeues the response message. In call mode, corresponding responses
are identified via the first 4 bytes of the message, called the
transaction ID. The kernel supplies distinct transaction IDs (always with the
-high bit set) for messages written with *zx_channel_call()*.
+high bit set) for messages written with [`zx_channel_call()`].
The process of sending a message via a channel has two steps. The first is to
atomically write the data into the channel and move ownership of all handles in
@@ -50,16 +50,22 @@
## SYSCALLS
-+ [channel_call](../syscalls/channel_call.md) - synchronously send a message and receive a reply
-+ [channel_create](../syscalls/channel_create.md) - create a new channel
-+ [channel_read](../syscalls/channel_read.md) - receive a message from a channel
-+ [channel_write](../syscalls/channel_write.md) - write a message to a channel
+ - [`zx_channel_call()`] - synchronously send a message and receive a reply
+ - [`zx_channel_create()`] - create a new channel
+ - [`zx_channel_read()`] - receive a message from a channel
+ - [`zx_channel_write()`] - write a message to a channel
<br>
-+ [object_wait_one](../syscalls/object_wait_one.md) - wait for signals on one object
+ - [`zx_object_wait_one()`] - wait for signals on one object
## SEE ALSO
+ [Zircon concepts](../concepts.md)
+ [Handles](../handles.md)
+
+[`zx_channel_call()`]: ../syscalls/channel_call.md
+[`zx_channel_create()`]: ../syscalls/channel_create.md
+[`zx_channel_read()`]: ../syscalls/channel_read.md
+[`zx_channel_write()`]: ../syscalls/channel_write.md
+[`zx_object_wait_one()`]: ../syscalls/object_wait_one.md
diff --git a/docs/objects/debuglog.md b/docs/objects/debuglog.md
index 2193a51..779af04 100644
--- a/docs/objects/debuglog.md
+++ b/docs/objects/debuglog.md
@@ -19,6 +19,10 @@
## SYSCALLS
-+ [debuglog_create](../syscalls/debuglog_create.md) - create a kernel managed debuglog reader or writer
-+ [debuglog_write](../syscalls/debuglog_write.md) - write log entry to debuglog
-+ [debuglog_read](../syscalls/debuglog_read.md) - read log entries from debuglog
+ - [`zx_debuglog_create()`] - create a kernel managed debuglog reader or writer
+ - [`zx_debuglog_write()`] - write log entry to debuglog
+ - [`zx_debuglog_read()`] - read log entries from debuglog
+
+[`zx_debuglog_create()`]: ../syscalls/debuglog_create.md
+[`zx_debuglog_read()`]: ../syscalls/debuglog_read.md
+[`zx_debuglog_write()`]: ../syscalls/debuglog_write.md
diff --git a/docs/objects/event.md b/docs/objects/event.md
index 0e583ba..3a89c8b 100644
--- a/docs/objects/event.md
+++ b/docs/objects/event.md
@@ -7,7 +7,7 @@
## SYNOPSIS
Events are user-signalable objects. The 8 signal bits reserved for
-userspace (*ZX_USER_SIGNAL_0* through *ZX_USER_SIGNAL_7*) may be set,
+userspace (**ZX_USER_SIGNAL_0** through **ZX_USER_SIGNAL_7**) may be set,
cleared, and waited upon.
## DESCRIPTION
@@ -16,10 +16,12 @@
## SYSCALLS
-+ [event_create](../syscalls/event_create.md) - create an event
-
-+ [object_signal](../syscalls/object_signal.md) - set or clear the user signals on an object
+ - [`zx_event_create()`] - create an event
+ - [`zx_object_signal()`] - set or clear the user signals on an object
## SEE ALSO
-+ [eventpair](eventpair.md) - linked pairs of signalable objects
+ - [eventpair](eventpair.md) - linked pairs of signalable objects
+
+[`zx_event_create()`]: ../syscalls/event_create.md
+[`zx_object_signal()`]: ../syscalls/object_signal.md
diff --git a/docs/objects/eventpair.md b/docs/objects/eventpair.md
index 16a8f3c..57e4697 100644
--- a/docs/objects/eventpair.md
+++ b/docs/objects/eventpair.md
@@ -7,8 +7,8 @@
## SYNOPSIS
Event Pairs are linked pairs of user-signalable objects. The 8 signal
-bits reserved for userspace (*ZX_USER_SIGNAL_0* through
-*ZX_USER_SIGNAL_7*) may be set or cleared on the local or opposing
+bits reserved for userspace (**ZX_USER_SIGNAL_0** through
+**ZX_USER_SIGNAL_7**) may be set or cleared on the local or opposing
endpoint of an Event Pair.
## DESCRIPTION
@@ -17,8 +17,11 @@
## SYSCALLS
-+ [eventpair_create](../syscalls/eventpair_create.md) - create a connected pair of events
+ - [`zx_eventpair_create()`] - create a connected pair of events
<br>
-+ [object_signal_peer](../syscalls/object_signal.md) - set or clear the user signals in the opposite end
+ - [`zx_object_signal_peer()`] - set or clear the user signals in the opposite end
+
+[`zx_eventpair_create()`]: ../syscalls/eventpair_create.md
+[`zx_object_signal_peer()`]: ../syscalls/object_signal.md
diff --git a/docs/objects/fifo.md b/docs/objects/fifo.md
index 453c163..16ddf0a 100644
--- a/docs/objects/fifo.md
+++ b/docs/objects/fifo.md
@@ -17,6 +17,10 @@
## SYSCALLS
-+ [fifo_create](../syscalls/fifo_create.md) - create a new fifo
-+ [fifo_read](../syscalls/fifo_read.md) - read data from a fifo
-+ [fifo_write](../syscalls/fifo_write.md) - write data to a fifo
+ - [`zx_fifo_create()`] - create a new fifo
+ - [`zx_fifo_read()`] - read data from a fifo
+ - [`zx_fifo_write()`] - write data to a fifo
+
+[`zx_fifo_create()`]: ../syscalls/fifo_create.md
+[`zx_fifo_read()`]: ../syscalls/fifo_read.md
+[`zx_fifo_write()`]: ../syscalls/fifo_write.md
diff --git a/docs/objects/futex.md b/docs/objects/futex.md
index 55673ae..f87ce54 100644
--- a/docs/objects/futex.md
+++ b/docs/objects/futex.md
@@ -47,10 +47,8 @@
so). It is up to userspace code to correctly atomically modify this
value across threads in order to build mutexes and so on.
-See the [futex_wait](../syscalls/futex_wait.md),
-[futex_wake](../syscalls/futex_wake.md),
-[futex_requeue](../syscalls/futex_requeue.md), and
-[futex_get_owner](../syscalls/futex_get_owner.md) man pages for more details.
+See the [`zx_futex_wait()`], [`zx_futex_wake()`], [`zx_futex_requeue()`], and
+[`zx_futex_get_owner()`] man pages for more details.
## RIGHTS
@@ -126,9 +124,10 @@
Ownership of a futex may be transferred by the kernel on behalf of the user
during a wake operation or a requeue operation. In the case of a requeue
operation, the target of the transfer is the wake_futex, not the requeue_futex.
-Ownership transfer only takes place when using the zx_futex_wake_single_owner or
-zx_futex_requeue_single_owner variants of the wake/requeue operations. The
-single_owner variants of these operations will release exactly one waiter, and
+Ownership transfer only takes place when using the
+[`zx_futex_wake_single_owner()`] or [`zx_futex_requeue_single_owner()`]
+variants of the wake/requeue operations. The `single_owner` variants of
+these operations will release exactly one waiter, and
assign ownership of the futex to the released thread.
+ If there are _no_ waiters during the wake operation, then there is already no
@@ -170,7 +169,14 @@
## SYSCALLS
-+ [futex_wait](../syscalls/futex_wait.md)
-+ [futex_wake](../syscalls/futex_wake.md)
-+ [futex_requeue](../syscalls/futex_requeue.md)
-+ [futex_get_owner](../syscalls/futex_get_owner.md)
+ - [`zx_futex_wait()`]
+ - [`zx_futex_wake()`]
+ - [`zx_futex_requeue()`]
+ - [`zx_futex_get_owner()`]
+
+[`zx_futex_get_owner()`]: ../syscalls/futex_get_owner.md
+[`zx_futex_requeue()`]: ../syscalls/futex_requeue.md
+[`zx_futex_requeue_single_owner()`]: ../syscalls/futex_requeue_single_owner.md
+[`zx_futex_wait()`]: ../syscalls/futex_wait.md
+[`zx_futex_wake()`]: ../syscalls/futex_wake.md
+[`zx_futex_wake_single_owner()`]: ../syscalls/futex_wake_single_owner.md
diff --git a/docs/objects/interrupts.md b/docs/objects/interrupts.md
index 795a59c..2844ca8 100644
--- a/docs/objects/interrupts.md
+++ b/docs/objects/interrupts.md
@@ -20,9 +20,16 @@
## SYSCALLS
-+ [interrupt_create](../syscalls/interrupt_create.md) - Create an interrupt handle
-+ [interrupt_destroy](../syscalls/interrupt_destroy.md) - Destroy an interrupt handle
-+ [interrupt_bind](../syscalls/interrupt_bind.md) - Bind an interrupt vector to interrupt handle
-+ [interrupt_wait](../syscalls/interrupt_wait.md) - Wait for an interrupt on an interrupt handle
-+ [interrupt_trigger](../syscalls/interrupt_trigger.md) - Triggers a virtual interrupt on an interrupt handle
-+ [interrupt_ack](../syscalls/interrupt_ack.md) - Acknowledge an interrupt and re-arm it
+ - [`zx_interrupt_create()`] - Create an interrupt handle
+ - [`zx_interrupt_destroy()`] - Destroy an interrupt handle
+ - [`zx_interrupt_bind()`] - Bind an interrupt vector to interrupt handle
+ - [`zx_interrupt_wait()`] - Wait for an interrupt on an interrupt handle
+ - [`zx_interrupt_trigger()`] - Triggers a virtual interrupt on an interrupt handle
+ - [`zx_interrupt_ack()`] - Acknowledge an interrupt and re-arm it
+
+[`zx_interrupt_ack()`]: ../syscalls/interrupt_ack.md
+[`zx_interrupt_bind()`]: ../syscalls/interrupt_bind.md
+[`zx_interrupt_create()`]: ../syscalls/interrupt_create.md
+[`zx_interrupt_destroy()`]: ../syscalls/interrupt_destroy.md
+[`zx_interrupt_trigger()`]: ../syscalls/interrupt_trigger.md
+[`zx_interrupt_wait()`]: ../syscalls/interrupt_wait.md
diff --git a/docs/objects/job.md b/docs/objects/job.md
index 73d83c6..9756e40 100644
--- a/docs/objects/job.md
+++ b/docs/objects/job.md
@@ -25,11 +25,14 @@
## SYSCALLS
-+ [job_create](../syscalls/job_create.md) - create a new child job.
-+ [process_create](../syscalls/process_create.md) - create a new process
- within a job.
-+ [job_set_policy](../syscalls/job_set_policy.md) - set policy for
- new processes in the job.
-+ [task_bind_exception_port](../syscalls/task_bind_exception_port.md) -
- attach an exception port to a task
-+ [task_kill](../syscalls/task_kill.md) - cause a task to stop running.
+ - [`zx_job_create()`] - create a new child job.
+ - [`zx_process_create()`] - create a new process within a job.
+ - [`zx_job_set_policy()`] - set policy for new processes in the job.
+ - [`zx_task_bind_exception_port()`] - attach an exception port to a task
+ - [`zx_task_kill()`] - cause a task to stop running.
+
+[`zx_job_create()`]: ../syscalls/job_create.md
+[`zx_job_set_policy()`]: ../syscalls/job_set_policy.md
+[`zx_process_create()`]: ../syscalls/process_create.md
+[`zx_task_bind_exception_port()`]: ../syscalls/task_bind_exception_port.md
+[`zx_task_kill()`]: ../syscalls/task_kill.md
diff --git a/docs/objects/pinned_memory_token.md b/docs/objects/pinned_memory_token.md
index 30903bd..d58fea1 100644
--- a/docs/objects/pinned_memory_token.md
+++ b/docs/objects/pinned_memory_token.md
@@ -14,19 +14,23 @@
PMTs are obtained by [pinning memory with a BTI object](../syscalls/bti_pin.md).
It is valid for the device associated with the BTI to access the memory represented
by the PMT for as long as the PMT object is around. When the PMT object is
-destroyed, either via **zx_handle_close**(), **zx_pmt_unpin**(), or process
+destroyed, either via [`zx_handle_close()`], [`zx_pmt_unpin()`], or process
termination, access to the represented memory becomes illegal (this is
enforced by hardware on systems with the capability to do so, such as IOMMUs).
-If a PMT object is destroyed by means other than **zx_pmt_unpin**(), the
+If a PMT object is destroyed by means other than [`zx_pmt_unpin()`], the
underlying memory is *quarantined*. See
[bus_transaction_initiator](bus_transaction_initiator.md) for more details.
## SEE ALSO
-+ [bus_transaction_initiator](bus_transaction_initiator.md) - Bus Transaction Initiators
+ - [bus_transaction_initiator](bus_transaction_initiator.md) - Bus Transaction Initiators
## SYSCALLS
-+ [bti_pin](../syscalls/bti_pin.md) - pin memory and grant access to it to the BTI
-+ [pmt_unpin](../syscalls/pmt_unpin.md) - revoke access and unpin memory
+ - [`zx_bti_pin()`] - pin memory and grant access to it to the BTI
+ - [`zx_pmt_unpin()`] - revoke access and unpin memory
+
+[`zx_bti_pin()`]: ../syscalls/bti_pin.md
+[`zx_handle_close()`]: ../syscalls/handle_close.md
+[`zx_pmt_unpin()`]: ../syscalls/pmt_unpin.md
diff --git a/docs/objects/port.md b/docs/objects/port.md
index 4043018..71811d8 100644
--- a/docs/objects/port.md
+++ b/docs/objects/port.md
@@ -17,6 +17,10 @@
## SYSCALLS
-+ [port_create](../syscalls/port_create.md) - create a port
-+ [port_queue](../syscalls/port_queue.md) - send a packet to a port
-+ [port_wait](../syscalls/port_wait.md) - wait for packets to arrive on a port
+ - [`zx_port_create()`] - create a port
+ - [`zx_port_queue()`] - send a packet to a port
+ - [`zx_port_wait()`] - wait for packets to arrive on a port
+
+[`zx_port_create()`]: ../syscalls/port_create.md
+[`zx_port_queue()`]: ../syscalls/port_queue.md
+[`zx_port_wait()`]: ../syscalls/port_wait.md
diff --git a/docs/objects/process.md b/docs/objects/process.md
index 7793cf0..4dbed9f 100644
--- a/docs/objects/process.md
+++ b/docs/objects/process.md
@@ -26,32 +26,42 @@
perspective of resource and permission limits, as well as lifetime control.
### Lifetime
-A process is created via `zx_process_create()` and its execution begins with
-`zx_process_start()`.
+A process is created via [`zx_process_create()`] and its execution begins with
+[`zx_process_start()`].
The process stops execution when:
+ the last thread is terminated or exits
-+ the process calls ``zx_process_exit()``
++ the process calls [`zx_process_exit()`]
+ the parent job terminates the process
+ the parent job is destroyed
-The call to `zx_process_start()` cannot be issued twice. New threads cannot
+The call to [`zx_process_start()`] cannot be issued twice. New threads cannot
be added to a process that was started and then its last thread has exited.
## SYSCALLS
-+ [process_create](../syscalls/process_create.md) - create a new process within a job
-+ [process_read_memory](../syscalls/process_read_memory.md) - read from a process's address space
-+ [process_start](../syscalls/process_start.md) - cause a new process to start executing
-+ [process_write_memory](../syscalls/process_write_memory.md) - write to a process's address space
-+ [process_exit](../syscalls/process_exit.md) - exit the current process
+ - [`zx_process_create()`] - create a new process within a job
+ - [`zx_process_read_memory()`] - read from a process's address space
+ - [`zx_process_start()`] - cause a new process to start executing
+ - [`zx_process_write_memory()`] - write to a process's address space
+ - [`zx_process_exit()`] - exit the current process
<br>
-+ [job_create](../syscalls/job_create.md) - create a new job within a parent job
+ - [`zx_job_create()`] - create a new job within a parent job
<br>
-+ [vmar_map](../syscalls/vmar_map.md) - Map memory into an address space range
-+ [vmar_protect](../syscalls/vmar_protect.md) - Change permissions on an address space range
-+ [vmar_unmap](../syscalls/vmar_unmap.md) - Unmap memory from an address space range
+ - [`zx_vmar_map()`] - Map memory into an address space range
+ - [`zx_vmar_protect()`] - Change permissions on an address space range
+ - [`zx_vmar_unmap()`] - Unmap memory from an address space range
+
+[`zx_job_create()`]: ../syscalls/job_create.md
+[`zx_process_create()`]: ../syscalls/process_create.md
+[`zx_process_exit()`]: ../syscalls/process_exit.md
+[`zx_process_read_memory()`]: ../syscalls/process_read_memory.md
+[`zx_process_start()`]: ../syscalls/process_start.md
+[`zx_process_write_memory()`]: ../syscalls/process_write_memory.md
+[`zx_vmar_map()`]: ../syscalls/vmar_map.md
+[`zx_vmar_protect()`]: ../syscalls/vmar_protect.md
+[`zx_vmar_unmap()`]: ../syscalls/vmar_unmap.md
diff --git a/docs/objects/resource.md b/docs/objects/resource.md
index 5f9ee95..eb2403e 100644
--- a/docs/objects/resource.md
+++ b/docs/objects/resource.md
@@ -23,7 +23,7 @@
**ZX_RSRC_KIND_ROOT**, **ZX_RSRC_KIND_HYPERVISOR**, **ZX_RSRC_KIND_MMIO**,
**ZX_RSRC_KIND_IOPORT**, **ZX_RSRC_KIND_IRQ**, **ZX_RSRC_KIND_VMEX**, and
**ZX_RSRC_KIND_SMC**. New resources may be created with a root resource by
-calling [resource_create](../syscalls/resource_create.md). An initial root
+calling [`zx_resource_create()`]. An initial root
resource is created by the kernel during boot and handed off to the first
userspace process started by userboot.
@@ -47,8 +47,12 @@
## SYSCALLS
-[interrupt_create](../syscalls/interrupt_create.md),
-[ioports_request](../syscalls/ioports_request.md),
-[resource_create](../syscalls/resource_create.md),
-[vmo_create_physical](../syscalls/vmo_create_physical.md)
+ - [`zx_interrupt_create()`]
+ - [`zx_ioports_request()`]
+ - [`zx_resource_create()`]
+ - [`zx_vmo_create_physical()`]
+[`zx_interrupt_create()`]: ../syscalls/interrupt_create.md
+[`zx_ioports_request()`]: ../syscalls/ioports_request.md
+[`zx_resource_create()`]: ../syscalls/resource_create.md
+[`zx_vmo_create_physical()`]: ../syscalls/vmo_create_physical.md
diff --git a/docs/objects/socket.md b/docs/objects/socket.md
index 611d7c8..fa7b698 100644
--- a/docs/objects/socket.md
+++ b/docs/objects/socket.md
@@ -11,12 +11,12 @@
## DESCRIPTION
-Data is written into one end of a socket via *zx_socket_write* and
-read from the opposing end via *zx_socket_read*.
+Data is written into one end of a socket via [`zx_socket_write()`] and
+read from the opposing end via [`zx_socket_read()`].
Upon creation, both ends of the socket are writable and readable. Via the
**ZX_SOCKET_SHUTDOWN_READ** and **ZX_SOCKET_SHUTDOWN_WRITE** options to
-*zx_socket_shutdown*, one end of the socket can be closed for reading and/or
+[`zx_socket_shutdown()`], one end of the socket can be closed for reading and/or
writing.
## PROPERTIES
@@ -25,20 +25,20 @@
**ZX_PROP_SOCKET_RX_THRESHOLD** size of the read threshold of a socket, in
bytes. When the bytes queued on the socket (available for reading) is equal to
-or greater than this value, the ZX_SOCKET_READ_THRESHOLD signal is asserted.
+or greater than this value, the **ZX_SOCKET_READ_THRESHOLD** signal is asserted.
Read threshold signalling is disabled by default (and when set, writing
a value of 0 for this property disables it).
**ZX_PROP_SOCKET_TX_THRESHOLD** size of the write threshold of a socket,
in bytes. When the space available for writing on the socket is equal to or
-greater than this value, the ZX_SOCKET_WRITE_THRESHOLD signal is asserted.
+greater than this value, the **ZX_SOCKET_WRITE_THRESHOLD** signal is asserted.
Write threshold signalling is disabled by default (and when set, writing a
value of 0 for this property disables it).
From the point of view of a socket handle, the receive buffer contains the data
-that is readable via **zx_socket_read**() from that handle (having been written
+that is readable via [`zx_socket_read()`] from that handle (having been written
from the opposing handle), and the transmit buffer contains the data that is
-written via **zx_socket_write**() to that handle (and readable from the opposing
+written via [`zx_socket_write()`] to that handle (and readable from the opposing
handle).
## SIGNALS
@@ -67,9 +67,9 @@
**ZX_SOCKET_CONTROL_WRITABLE** data may be written to the socket control plane.
-**ZX_SOCKET_SHARE** a socket may be sent via *zx_socket_share*.
+**ZX_SOCKET_SHARE** a socket may be sent via [`zx_socket_share()`].
-**ZX_SOCKET_ACCEPT** a socket may be received via *zx_socket_accept*.
+**ZX_SOCKET_ACCEPT** a socket may be received via [`zx_socket_accept()`].
**ZX_SOCKET_READ_THRESHOLD** data queued up on socket for reading exceeds
the read threshold.
@@ -79,9 +79,16 @@
## SYSCALLS
-+ [socket_accept](../syscalls/socket_accept.md) - receive a socket via a socket
-+ [socket_create](../syscalls/socket_create.md) - create a new socket
-+ [socket_read](../syscalls/socket_read.md) - read data from a socket
-+ [socket_share](../syscalls/socket_share.md) - share a socket via a socket
-+ [socket_shutdown](../syscalls/socket_shutdown.md) - prevent reading or writing
-+ [socket_write](../syscalls/socket_write.md) - write data to a socket
+ - [`zx_socket_accept()`] - receive a socket via a socket
+ - [`zx_socket_create()`] - create a new socket
+ - [`zx_socket_read()`] - read data from a socket
+ - [`zx_socket_share()`] - share a socket via a socket
+ - [`zx_socket_shutdown()`] - prevent reading or writing
+ - [`zx_socket_write()`] - write data to a socket
+
+[`zx_socket_accept()`]: ../syscalls/socket_accept.md
+[`zx_socket_create()`]: ../syscalls/socket_create.md
+[`zx_socket_read()`]: ../syscalls/socket_read.md
+[`zx_socket_share()`]: ../syscalls/socket_share.md
+[`zx_socket_shutdown()`]: ../syscalls/socket_shutdown.md
+[`zx_socket_write()`]: ../syscalls/socket_write.md
diff --git a/docs/objects/task.md b/docs/objects/task.md
index 97eee63..57587e7 100644
--- a/docs/objects/task.md
+++ b/docs/objects/task.md
@@ -16,5 +16,8 @@
## SYSCALLS
-+ [task_bind_exception_port](../syscalls/task_bind_exception_port.md) - attach an exception port to a task
-+ [task_kill](../syscalls/task_kill.md) - cause a task to stop running
+ - [`zx_task_bind_exception_port()`] - attach an exception port to a task
+ - [`zx_task_kill()`] - cause a task to stop running
+
+[`zx_task_bind_exception_port()`]: ../syscalls/task_bind_exception_port.md
+[`zx_task_kill()`]: ../syscalls/task_kill.md
diff --git a/docs/objects/thread.md b/docs/objects/thread.md
index 57dda21..3e444eb 100644
--- a/docs/objects/thread.md
+++ b/docs/objects/thread.md
@@ -48,16 +48,16 @@
## SYSCALLS
-+ [`zx_thread_create()`] - create a new thread within a process
-+ [`zx_thread_exit()`] - exit the current thread
-+ [`zx_thread_read_state()`] - read register state from a thread
-+ [`zx_thread_start()`] - cause a new thread to start executing
-+ [`zx_thread_write_state()`] - modify register state of a thread
+ - [`zx_thread_create()`] - create a new thread within a process
+ - [`zx_thread_exit()`] - exit the current thread
+ - [`zx_thread_read_state()`] - read register state from a thread
+ - [`zx_thread_start()`] - cause a new thread to start executing
+ - [`zx_thread_write_state()`] - modify register state of a thread
<br>
-+ [`zx_task_bind_exception_port()`] - attach an exception port to a task
-+ [`zx_task_kill()`] - cause a task to stop running
+ - [`zx_task_bind_exception_port()`] - attach an exception port to a task
+ - [`zx_task_kill()`] - cause a task to stop running
[`zx_futex_wake_handle_close_thread_exit()`]: ../syscalls/futex_wake_handle_close_thread_exit.md
[`zx_object_get_child()`]: ../syscalls/object_get_child.md
diff --git a/docs/objects/timer.md b/docs/objects/timer.md
index aaef342..81ff38c 100644
--- a/docs/objects/timer.md
+++ b/docs/objects/timer.md
@@ -12,33 +12,35 @@
## DESCRIPTION
Like other waitable objects, timers can be waited on via
-[`zx_object_wait_one()`](../syscalls/object_wait_one.md),
-[`zx_object_wait_many()`](../syscalls/object_wait_many.md), or
-[`zx_object_wait_async()`](../syscalls/object_wait_async.md).
+[`zx_object_wait_one()`], [`zx_object_wait_many()`], or
+[`zx_object_wait_async()`].
A given timer can be used over and over.
Once **ZX_TIMER_SIGNALED** is asserted, it will remain asserted until
-the timer is canceled ([timer_cancel]) or reset ([timer_set]).
+the timer is canceled ([`zx_timer_cancel()`]) or reset ([`zx_timer_set()`]).
The typical lifecycle is:
1. `zx_timer_create()`
2. `zx_timer_set()`
3. wait for the timer to be signaled
-4. optinally reset and reuse the timer (i.e. goto #2)
+4. optionally reset and reuse the timer (i.e. goto #2)
5. `zx_handle_close()`
## SYSCALLS
-+ [timer_create] - create a timer
-+ [timer_set] - set a timer
-+ [timer_cancel] - cancel a timer
+ - [`zx_timer_create()`] - create a timer
+ - [`zx_timer_set()`] - set a timer
+ - [`zx_timer_cancel()`] - cancel a timer
## SEE ALSO
+ [timer slack](../timer_slack.md)
-[timer_create]: ../syscalls/timer_create.md
-[timer_set]: ../syscalls/timer_set.md
-[timer_cancel]: ../syscalls/timer_cancel.md
+[`zx_object_wait_one()`]: ../syscalls/object_wait_one.md
+[`zx_object_wait_many()`]: ../syscalls/object_wait_many.md
+[`zx_object_wait_async()`]: ../syscalls/object_wait_async.md
+[`zx_timer_create()`]: ../syscalls/timer_create.md
+[`zx_timer_set()`]: ../syscalls/timer_set.md
+[`zx_timer_cancel()`]: ../syscalls/timer_cancel.md
diff --git a/docs/objects/vm_address_region.md b/docs/objects/vm_address_region.md
index 3d9264f..8bc4539 100644
--- a/docs/objects/vm_address_region.md
+++ b/docs/objects/vm_address_region.md
@@ -15,34 +15,34 @@
address space.
Every process starts with a single VMAR (the root VMAR) that spans the entire
-address space (see [process_create](../syscalls/process_create.md)). Each VMAR
+address space (see [`zx_process_create()`]). Each VMAR
can be logically divided up into any number of non-overlapping parts, each
representing a child VMARs, a virtual memory mapping, or a gap. Child VMARs
-are created using [vmar_allocate](../syscalls/vmar_allocate.md). VM mappings
-are created using [vmar_map](../syscalls/vmar_map.md).
+are created using [`zx_vmar_allocate()`]. VM mappings
+are created using [`zx_vmar_map()`].
VMARs have a hierarchical permission model for allowable mapping permissions.
For example, the root VMAR allows read, write, and executable mapping. One
could create a child VMAR that only allows read and write mappings, in which
it would be illegal to create a child that allows executable mappings.
-When a VMAR is created using vmar_allocate, its parent VMAR retains a reference
+When a VMAR is created using [`zx_vmar_allocate()`], its parent VMAR retains a reference
to it. Because of this, if all handles to the child VMAR are closed, the child
and its descendants will remain active in the address space. In order to
-disconnect the child from the address space, [vmar_destroy](../syscalls/vmar_destroy.md)
+disconnect the child from the address space, [`zx_vmar_destroy()`]
must be called on a handle to the child.
By default, all allocations of address space are randomized. At VMAR
creation time, the caller can choose which randomization algorithm is used.
The default allocator attempts to spread allocations widely across the full
width of the VMAR. The alternate allocator, selected with
-*ZX_VM_COMPACT*, attempts to keep allocations close together within the
+**ZX_VM_COMPACT**, attempts to keep allocations close together within the
VMAR, but at a random location within the range. It is recommended to use
the default allocator.
VMARs optionally support a fixed-offset mapping mode (called specific mapping).
This mode can be used to create guard pages or ensure the relative locations of
-mappings. Each VMAR may have the *ZX_VM_CAN_MAP_SPECIFIC* permission,
+mappings. Each VMAR may have the **ZX_VM_CAN_MAP_SPECIFIC** permission,
regardless of whether or not its parent VMAR had that permission.
## EXAMPLE
@@ -91,12 +91,19 @@
## SEE ALSO
-+ [vm_object](vm_object.md) - Virtual Memory Objects
+ - [vm_object](vm_object.md) - Virtual Memory Objects
## SYSCALLS
-+ [vmar_allocate](../syscalls/vmar_allocate.md) - create a new child VMAR
-+ [vmar_map](../syscalls/vmar_map.md) - map a VMO into a process
-+ [vmar_unmap](../syscalls/vmar_unmap.md) - unmap a memory region from a process
-+ [vmar_protect](../syscalls/vmar_protect.md) - adjust memory access permissions
-+ [vmar_destroy](../syscalls/vmar_destroy.md) - destroy a VMAR and all of its children
+ - [`zx_vmar_allocate()`] - create a new child VMAR
+ - [`zx_vmar_map()`] - map a VMO into a process
+ - [`zx_vmar_unmap()`] - unmap a memory region from a process
+ - [`zx_vmar_protect()`] - adjust memory access permissions
+ - [`zx_vmar_destroy()`] - destroy a VMAR and all of its children
+
+[`zx_process_create()`]: ../syscalls/process_create.md
+[`zx_vmar_allocate()`]: ../syscalls/vmar_allocate.md
+[`zx_vmar_destroy()`]: ../syscalls/vmar_destroy.md
+[`zx_vmar_map()`]: ../syscalls/vmar_map.md
+[`zx_vmar_protect()`]: ../syscalls/vmar_protect.md
+[`zx_vmar_unmap()`]: ../syscalls/vmar_unmap.md
diff --git a/docs/objects/vm_object.md b/docs/objects/vm_object.md
index 183e968..8d45085 100644
--- a/docs/objects/vm_object.md
+++ b/docs/objects/vm_object.md
@@ -15,32 +15,42 @@
They are the standard method of sharing memory between processes, as well as between the kernel and
userspace.
-VMOs are created with [vmo_create](../syscalls/vmo_create.md) and basic I/O can be
-performed on them with [vmo_read](../syscalls/vmo_read.md) and [vmo_write](../syscalls/vmo_write.md).
-A VMO's size may be set using [vmo_set_size](../syscalls/vmo_set_size.md).
-Conversely, [vmo_get_size](../syscalls/vmo_get_size.md) will retrieve a VMO's current size.
+VMOs are created with [`zx_vmo_create()`] and basic I/O can be
+performed on them with [`zx_vmo_read()`] and [`zx_vmo_write()`].
+A VMO's size may be set using [`zx_vmo_set_size()`].
+Conversely, [`zx_vmo_get_size()`] will retrieve a VMO's current size.
The size of a VMO will be rounded up to the next page size boundary by the kernel.
-Pages are committed (allocated) for VMOs on demand through [vmo_read](../syscalls/vmo_read.md), [vmo_write](../syscalls/vmo_write.md), or by writing to a mapping of the VMO created using [vmar_map](../syscalls/vmar_map.md). Pages can be committed and decommitted from a VMO manually by calling
-[vmo_op_range](../syscalls/vmo_op_range.md) with the *ZX_VMO_OP_COMMIT* and *ZX_VMO_OP_DECOMMIT*
-operations, but this should be considered a low level operation. [vmo_op_range](../syscalls/vmo_op_range.md) can also be used for cache and locking operations against pages a VMO holds.
+Pages are committed (allocated) for VMOs on demand through [`zx_vmo_read()`], [`zx_vmo_write()`], or by writing to a mapping of the VMO created using [`zx_vmar_map()`]. Pages can be committed and decommitted from a VMO manually by calling
+[`zx_vmo_op_range()`] with the **ZX_VMO_OP_COMMIT** and **ZX_VMO_OP_DECOMMIT**
+operations, but this should be considered a low level operation. [`zx_vmo_op_range()`] can also be used for cache and locking operations against pages a VMO holds.
Processes with special purpose use cases involving cache policy can use
-[vmo_set_cache_policy](../syscalls/vmo_set_cache_policy.md) to change the policy of a given VMO.
+[`zx_vmo_set_cache_policy()`] to change the policy of a given VMO.
This use case typically applies to device drivers.
## SYSCALLS
-+ [vmo_create](../syscalls/vmo_create.md) - create a new vmo
-+ [vmo_read](../syscalls/vmo_read.md) - read from a vmo
-+ [vmo_write](../syscalls/vmo_write.md) - write to a vmo
-+ [vmo_get_size](../syscalls/vmo_get_size.md) - obtain the size of a vmo
-+ [vmo_set_size](../syscalls/vmo_set_size.md) - adjust the size of a vmo
-+ [vmo_op_range](../syscalls/vmo_op_range.md) - perform an operation on a range of a vmo
-+ [vmo_set_cache_policy](../syscalls/vmo_set_cache_policy.md) - set the caching policy for pages held by a vmo
+ - [`zx_vmo_create()`] - create a new vmo
+ - [`zx_vmo_read()`] - read from a vmo
+ - [`zx_vmo_write()`] - write to a vmo
+ - [`zx_vmo_get_size()`] - obtain the size of a vmo
+ - [`zx_vmo_set_size()`] - adjust the size of a vmo
+ - [`zx_vmo_op_range()`] - perform an operation on a range of a vmo
+ - [`zx_vmo_set_cache_policy()`] - set the caching policy for pages held by a vmo
<br>
-+ [vmar_map](../syscalls/vmar_map.md) - map a VMO into a process
-+ [vmar_unmap](../syscalls/vmar_unmap.md) - unmap memory from a process
+ - [`zx_vmar_map()`] - map a VMO into a process
+ - [`zx_vmar_unmap()`] - unmap memory from a process
+
+[`zx_vmar_map()`]: ../syscalls/vmar_map.md
+[`zx_vmar_unmap()`]: ../syscalls/vmar_unmap.md
+[`zx_vmo_create()`]: ../syscalls/vmo_create.md
+[`zx_vmo_get_size()`]: ../syscalls/vmo_get_size.md
+[`zx_vmo_op_range()`]: ../syscalls/vmo_op_range.md
+[`zx_vmo_read()`]: ../syscalls/vmo_read.md
+[`zx_vmo_set_cache_policy()`]: ../syscalls/vmo_set_cache_policy.md
+[`zx_vmo_set_size()`]: ../syscalls/vmo_set_size.md
+[`zx_vmo_write()`]: ../syscalls/vmo_write.md
