[docs] Add objects.md and objects/foo.md pages

Change-Id: I95b6a42330f8b9d3711c5c894aeaf88a9256f2de
Esse commit está contido em:
George Kulakowski
2017-03-04 12:37:34 -08:00
commit de CQ bot account: commit-bot@chromium.org
commit 7c642bcc6a
21 arquivos alterados com 373 adições e 72 exclusões
+15 -4
Ver Arquivo
@@ -16,19 +16,30 @@ Magenta actively manages the following resources:
## Kernel objects for applications
+ [Channel](objects/channel.md)
+ [Socket](objects/socket.md)
+ [FIFO](objects/fifo.md)
+ [Process](objects/process.md)
+ [Thread](objects/thread.md)
+ [Job](objects/job.md)
+ [Task](objects/task.md)
+ [Event](objects/event.md)
+ [Channel](objects/channel.md)
+ [VMObject](objects/vm_object.md)
+ [Virtual Memory Address Region](objects/vm_address_region.md)
+ [Port](objects/port.md)
+ [Event Pair](objects/eventpair.md)
+ [Futex](objects/futex.md)
+ [Virtual Memory Object](objects/vm_object.md)
+ [Virtual Memory Address Region](objects/vm_address_region.md)
+ [Port](objects/port.md)
+ [Waitset](objects/waitset.md)
## Kernel objects for drivers
+ [Interrupt request](objects/interrupt_request.md)
+ [Resource](objects/resource.md)
+ [Log](objects/log.md)
## Kernel Object and LK
Some kernel objects wrap one or more LK-level constructs. For example the
+38
Ver Arquivo
@@ -0,0 +1,38 @@
# Magenta Kernel Objects
## Handles and Objects
+ [handle](handles.md)
+ [object](kernel_objects.md)
## IPC
+ [channel](objects/channel.md)
+ [socket](objects/socket.md)
+ [fifo](objects/fifo.md)
## Signaling
+ [event](objects/event.md)
+ [eventpair](objects/eventpair.md)
+ [futex](objects/futex.md)
## Waiting
+ [waitset](objects/waitset.md)
+ [port](objects/port.md)
## Tasks
+ [thread](objects/thread.md)
+ [process](objects/process.md)
+ [job](objects/job.md)
+ [task](objects/task.md)
## Memory and address space
+ [vmo](objects/vm_object.md)
+ [vmar](objects/vm_address_region.md)
## Resources
+ [resource](objects/resource.md)
## Interrupts
+ [interrupt_request](objects/interrupt_request.md)
## Logs
+ [log](objects/log.md)
+50 -6
Ver Arquivo
@@ -1,4 +1,4 @@
# Channel Object
# Channel
## NAME
@@ -6,14 +6,58 @@ channel - Bidirectional interprocess communication
## SYNOPSIS
TODO
A channel is a bidirectional transport of messages consisting of some
amount of byte data and some number of handles.
## DESCRIPTION
TODO
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 *mx_channel_write()* enqueues one message,
and a call to *mx_channel_read()* dequeues one message (if any are
queued). A thread can block until messages are pending via
*mx_object_wait_one()* or other waiting mechanisms.
Alternatively, a call to *mx_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. Coming up with distinct transaction IDs is up to the
users of *mx_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 the message into this channel. This
operation cannot partially succeed: at the end of the call, all
handles are either still in the calling process's handle table or are
all in the channel. The second operation is similar: after a channel
read, all the handles in the next message to read are either
atomically moved into the process's handle table, all remain in the
channel, or are discarded (only when the
**MX_CHANNEL_READ_MAY_DISCARD** option is given).
Unlike many other kernel object types, channels are not
duplicatable. Thus there is only ever one handle associated to a
handle endpoint.
Because of these properties (that channel messages move their handle
contents atomically, and that channels are not duplicatable), the
kernel is able to avoid complicated garbage collection, lifetime
management, or cycle detection simply by enforcing the simple rule
that a channel handle may not be written into itself.
## 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
<br>
+ [object_wait_one](../syscalls/object_wait_one.md) - wait for signals on one object
## SEE ALSO
[channel_create](../syscalls/channel_create.md)
[channel_read](../syscalls/channel_read.md)
[channel_write](../syscalls/channel_write.md)
+ [Magenta concepts](../concepts.md)
+ [Handles](../handles.md)
+14 -2
Ver Arquivo
@@ -1,4 +1,4 @@
# Event Object
# Event
## NAME
@@ -6,8 +6,20 @@ event - Signalable event for concurrent programming
## SYNOPSIS
TODO
Events are user-signalable objects. The 8 signal bits reserved for
userspace (*MX_USER_SIGNAL_0* through *MX_USER_SIGNAL_7*) may be set,
cleared, and waited upon.
## DESCRIPTION
TODO
## 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
## SEE ALSO
+ [eventpair](eventpair.md) - linked pairs of signalable objects
+24
Ver Arquivo
@@ -0,0 +1,24 @@
# Event Pair
## NAME
eventpair - Mutually signalable pair of events for concurrent programming
## SYNOPSIS
Event Pairs are linked pairs of user-signalable objects. The 8 signal
bits reserved for userspace (*MX_USER_SIGNAL_0* through
*MX_USER_SIGNAL_7*) may be set or cleared on the local or opposing
endpoint of an Event Pair.
## DESCRIPTION
TODO
## SYSCALLS
+ [eventpair_create](../syscalls/eventpair_create.md) - create a connected pair of events
<br>
+ [object_signal_peer](../syscalls/object_signal.md) - set or clear the user signals in the opposite end
+22
Ver Arquivo
@@ -0,0 +1,22 @@
# FIFO
## NAME
FIFO - first-in first-out interprocess queue
## SYNOPSIS
FIFOs are intended to be the control plane for shared memory
transports. Their read and write operations are more efficient than
[sockets](socket.md) or [channels](channel.md), but there are severe
restrictions on the size of elements and buffers.
## DESCRIPTION
TODO
## 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
+15 -5
Ver Arquivo
@@ -1,6 +1,10 @@
# Futexes
# Futex
## What is a futex?
## NAME
futex - A primitive for creating userspace synchronization tools.
## SYNOPSIS
A **futex** is a Fast Userspace muTEX. It is a low level
synchronization primitive which is a building block for higher level
@@ -9,7 +13,7 @@ APIs such as `pthread_mutex_t` and `pthread_cond_t`.
Futexes are designed to not enter the kernel or allocate kernel
resources in the uncontested case.
## API
## DESCRIPTION
The magenta futex implementation currently supports three operations:
@@ -34,7 +38,7 @@ See the [futex_wait](../syscalls/futex_wait.md),
[futex_wake](../syscalls/futex_wake.md), and
[futex_requeue](../syscalls/futex_requeue.md) man pages for more details.
## Differences from Linux futexes
### Differences from Linux futexes
Note that all of the magenta futex operations key off of the virtual
address of an userspace pointer. This differs from the Linux
@@ -47,7 +51,7 @@ futex unmodified from the kernel. Other potential operations, such as
Linux's `FUTEX_WAKE_OP`, requires atomic manipulation of the value
from the kernel, which our current implementation does not require.
## Papers about futexes
### Papers about futexes
- [Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux](https://www.kernel.org/doc/ols/2002/ols2002-pages-479-495.pdf), Hubertus Franke and Rusty Russell
@@ -74,3 +78,9 @@ from the kernel, which our current implementation does not require.
benchmarks and analysis. Contains a detailed explanation of the "parking
lot" concept, which allows very compact representation of user-space
mutexes.
## SYSCALLS
+ [futex_wait](../syscalls/futex_wait.md)
+ [futex_wake](../syscalls/futex_wake.md)
+ [futex_requeue](../syscalls/futex_requeue.md)
+13 -3
Ver Arquivo
@@ -1,13 +1,23 @@
# Interrupt Request Object
# Interrupt Event
## NAME
interrupt\_request - Usermode I/O interrupt delivery
interrupt\_event - Usermode I/O interrupt delivery
## SYNOPSIS
TODO
Interrupt events allow userspace to create, signal, and wait on
hardware interrupts.
## DESCRIPTION
TODO
## NOTES
Interrupt Objects are private to the DDK and not generally available
to userspace processes.
## SYSCALLS
TODO(MG-525)
+13 -4
Ver Arquivo
@@ -1,4 +1,4 @@
# Job Object
# Job
## NAME
@@ -23,7 +23,16 @@ A job is an object consisting of the following:
Jobs control "applications" that are composed of more than one process to be
controlled as a single entity.
## SEE ALSO
## SYSCALLS
[job_create](../syscalls/job_create.md),
[process_create](../syscalls/process_create.md)
+ [job_create](../syscalls/job_create.md) - create a new job within a job
<br>
+ [process_create](../syscalls/process_create.md) - create a new process within a job
<br>
+ [task_resume](../syscalls/task_resume.md) - cause a suspended task to continue running
+ [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
+25
Ver Arquivo
@@ -0,0 +1,25 @@
# Log
## NAME
Log - Kernel debug log
## SYNOPSIS
Log objects allow userspace to read and write to kernel debug logs.
## DESCRIPTION
TODO
## NOTES
Log objects will likely cease being generally available to userspace
processes in the future. They are intended for internal logging of
the kernel and device drivers.
## SYSCALLS
+ log_create - create a kernel managed log reader or writer
+ log_write - write log entry to log
+ log_read - read log entries from log
+11 -8
Ver Arquivo
@@ -1,20 +1,23 @@
# Port Object
# Port
## NAME
port - Signalling and mailbox primitive
port - Signaling and mailbox primitive
## SYNOPSIS
TODO
Ports allow threads to wait for packets to be delivered from various
events. These events include explicit queueing on the port,
asynchronous waits on other handles bound to the port, and
asynchronous message delivery from IPC transports.
## DESCRIPTION
TODO
## SEE ALSO
## SYSCALLS
[port_create](../syscalls/port_create.md)
[port_bind](../syscalls/port_bind.md)
[port_queue](../syscalls/port_queue.md)
[port_wait](../syscalls/port_wait.md)
+ [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
+ [port_bind](../syscalls/port_bind.md) - bind an object to a port
+20 -10
Ver Arquivo
@@ -1,4 +1,4 @@
# Process Object
# Process
## NAME
@@ -6,8 +6,9 @@ process - Process abstraction
## SYNOPSIS
A magenta process is an instance of a program in the traditional sense: a set
of instructions which will be executed by one or more threads.
A magenta process is an instance of a program in the traditional
sense: a set of instructions which will be executed by one or more
threads, along with a collection of resources.
## DESCRIPTION
@@ -32,11 +33,20 @@ is closed. [⚠ not implemented].
Next, the main binary is loaded into the process via `sys_process_load()` and
its execution begins with `sys_process_start()`.
## SEE ALSO
## SYSCALLS
[process_create](../syscalls/process_create.md),
[process_start](../syscalls/process_start.md),
[job_create](../syscalls/job_create.md),
[vmar_map](../syscalls/vmar_map.md),
[vmar_protect](../syscalls/vmar_protect.md),
[vmar_unmap](../syscalls/vmar_unmap.md).
+ [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
<br>
+ [job_create](../syscalls/job_create.md) - 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
+21
Ver Arquivo
@@ -0,0 +1,21 @@
# Resource
## NAME
resource - Hierarchical resource rights and accounting
## SYNOPSIS
TODO
## DESCRIPTION
TODO
## NOTES
Resources are currently experimental and private to the DDK.
## SYSCALLS
TODO(MG-525)
+26
Ver Arquivo
@@ -0,0 +1,26 @@
# Socket
## NAME
Socket - Bidirectional streaming IPC transport
## SYNOPSIS
Sockets are a bidirectional stream transport. Unlike channels, sockets
only move data (not handles).
## DESCRIPTION
Data is written into one end of a socket via *mx_socket_write* and
read from the opposing end via *mx_socket_read*.
Upon creation, both ends of the socket are writable and readable. Via
the **MX_SOCKET_HALF_CLOSE** option to *mx_socket_write*, one end of
the socket can be closed for reading (and the opposing end for
writing).
## SYSCALLS
+ [socket_create](../syscalls/socket_create.md) - create a new socket
+ [socket_read](../syscalls/socket_read.md) - read data from a socket
+ [socket_write](../syscalls/socket_write.md) - write data to a socket
+21
Ver Arquivo
@@ -0,0 +1,21 @@
# Task
## NAME
Task - "Runnable" subclass of kernel objects (threads, processes, and jobs)
## SYNOPSIS
[Threads](thread.md), [processes](process.md), and [jobs](job.md) objects
are all tasks. They share the ability to be suspended, resumed, and
killed.
## DESCRIPTION
TODO
## SYSCALLS
+ [task_resume](../syscalls/task_resume.md) - cause a suspended task to continue running
+ [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
+13 -5
Ver Arquivo
@@ -1,4 +1,4 @@
# Thread Object
# Thread
## NAME
@@ -24,8 +24,16 @@ the previously loaded binary. Or it can be created by calling
A thread terminates when it `return`s from executing the routine specified as
the entrypoint or by calling `sys_thread_exit()`.
## SEE ALSO
## SYSCALLS
[thread_create](../syscalls/thread_create.md)
[thread_start](../syscalls/thread_start.md)
[thread_exit](../syscalls/thread_exit.md)
+ [thread_create](../syscalls/thread_create.md) - create a new thread within a process
+ [thread_exit](../syscalls/thread_exit.md) - exit the current thread
+ [thread_read_state](../syscalls/thread_read_state.md) - read register state from a thread
+ [thread_start](../syscalls/thread_start.md) - cause a new thread to start executing
+ [thread_write_state](../syscalls/thread_write_state.md) - modify register state of a thread
<br>
+ [task_resume](../syscalls/task_resume.md) - cause a suspended task to continue running
+ [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
+9 -6
Ver Arquivo
@@ -84,9 +84,12 @@ mx_status_t map_with_guard(mx_handle_t vmar, size_t before, size_t after,
## SEE ALSO
[vm_object](vm_object.md),
[vmar_allocate](../syscalls/vmar_allocate.md),
[vmar_destroy](../syscalls/vmar_destroy.md),
[vmar_map](../syscalls/vmar_map.md),
[vmar_protect](../syscalls/vmar_protect.md),
[vmar_unmap](../syscalls/vmar_unmap.md),
+ [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
+12 -9
Ver Arquivo
@@ -23,13 +23,16 @@ VMO using [vmar_map](../syscalls/vmar_map.md). Pages can be commited and decommi
[vmo_op_range](../syscalls/vmo_op_range.md) with the *MX_VMO_OP_COMMIT* and *MX_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.
## SEE ALSO
## SYSCALLS
[vmo_create](../syscalls/vmo_create.md),
[vmo_op_range](../syscalls/vmo_op_range.md),
[vmo_get_size](../syscalls/vmo_get_size.md),
[vmo_set_size](../syscalls/vmo_set_size.md),
[vmo_read](../syscalls/vmo_read.md),
[vmo_write](../syscalls/vmo_write.md),
[vmar_map](../syscalls/vmar_map.md),
[vmar_unmap](../syscalls/vmar_unmap.md).
+ [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
<br>
+ [vmar_map](../syscalls/vmar_map.md) - map a VMO into a process
+ [vmar_unmap](../syscalls/vmar_unmap.md) - unmap memory from a process
+6 -6
Ver Arquivo
@@ -1,4 +1,4 @@
# Waitset Object
# Waitset
## NAME
@@ -15,9 +15,9 @@ TODO
TODO
## SEE ALSO
## SYSCALLS
[waitset_create](../syscalls/waitset_create.md)
[waitset_add](../syscalls/waitset_add.md)
[waitset_remove](../syscalls/waitset_remove.md)
[waitset_wait](../syscalls/waitset_wait.md)
+ [waitset_create](../syscalls/waitset_create.md) - create a new waitset
+ [waitset_add](../syscalls/waitset_add.md) - add an entry to a waitset
+ [waitset_remove](../syscalls/waitset_remove.md) - remove an entry from a waitset
+ [waitset_wait](../syscalls/waitset_wait.md) - wait for one or more entries to be signalled
+3 -3
Ver Arquivo
@@ -74,9 +74,9 @@
+ [port_cancel](syscalls/port_cancel.md) - cancel notificaitons from async_wait
## Futexes
+ [futex_wait](syscalls/futex_wait.md)
+ [futex_wake](syscalls/futex_wake.md)
+ [futex_requeue](syscalls/futex_requeue.md)
+ [futex_wait](syscalls/futex_wait.md) - wait on a futex
+ [futex_wake](syscalls/futex_wake.md) - wake waiters on a futex
+ [futex_requeue](syscalls/futex_requeue.md) - wake some waiters and requeue other waiters
## Virtual Memory Objects (VMOs)
+ [vmo_create](syscalls/vmo_create.md) - create a new vmo
+2 -1
Ver Arquivo
@@ -1,4 +1,5 @@
* [Magenta](/README.md)
* [Concepts](/docs/concepts.md)
* [Objects](/docs/objects.md)
* [Syscalls](/docs/syscalls.md)
* [Getting Started](/docs/getting_started.md)
* [Getting Started](/docs/getting_started.md)