zhenxing
/
zCore
forked from rcore-os/zCore
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

improved the doc of Zircon system calls

This commit is contained in:
iLifetruth 2020-08-12 16:21:12 +08:00
parent f7152c709c
commit 4ad16f5177
21 changed files with 158 additions and 116 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
zircon-syscall/src/channel.rs
View File

@ -9,8 +9,8 @@ use {
}; };
impl Syscall<'_> { impl Syscall<'_> {
/// Read a message from a channel.
#[allow(clippy::too_many_arguments)] #[allow(clippy::too_many_arguments)]
/// Read/Receive a message from a channel.
pub fn sys_channel_read( pub fn sys_channel_read(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -74,7 +74,7 @@ impl Syscall<'_> {
} }
Ok(()) Ok(())
} }
/// Write a message to a channel. /// Write a message to a channel.
pub fn sys_channel_write( pub fn sys_channel_write(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -114,7 +114,7 @@ impl Syscall<'_> {
channel.write(MessagePacket { data, handles })?; channel.write(MessagePacket { data, handles })?;
Ok(()) Ok(())
} }
/// Create a channel. /// Create a new channel.
pub fn sys_channel_create( pub fn sys_channel_create(
&self, &self,
options: u32, options: u32,
@ -134,6 +134,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
///
pub async fn sys_channel_call_noretry( pub async fn sys_channel_call_noretry(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -210,7 +211,7 @@ impl Syscall<'_> {
Err(ZxError::BAD_STATE) Err(ZxError::BAD_STATE)
} }
} }
/// Write a message to a channel. /// Write a message to a channel.
pub fn sys_channel_write_etc( pub fn sys_channel_write_etc(
&self, &self,
handle: HandleValue, handle: HandleValue,

11
zircon-syscall/src/cprng.rs
View File

@ -1,13 +1,16 @@
use super::*; use super::*;
/// Draw 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 bytes to seed a user-space random number generator for better performance.
impl Syscall<'_> { impl Syscall<'_> {
/// Draw 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 bytes to seed a user-space random number generator for better performance.
pub fn sys_cprng_draw_once(&self, mut buf: UserOutPtr<u8>, len: usize) -> ZxResult { pub fn sys_cprng_draw_once(&self, mut buf: UserOutPtr<u8>, len: usize) -> ZxResult {
info!("cprng_draw_once: buf=({:?}; {:?})", buf, len); info!("cprng_draw_once: buf=({:?}; {:?})", buf, len);
let mut res = vec![0u8; len]; let mut res = vec![0u8; len];
kernel_hal::fill_random(&mut res); // Fill random bytes to the buffer // Fill random bytes to the buffer
kernel_hal::fill_random(&mut res);
buf.write_array(&res)?; buf.write_array(&res)?;
Ok(()) Ok(())
} }

26
zircon-syscall/src/ddk.rs
View File

@ -39,9 +39,10 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Creates a new bus transaction initiator. /// Creates a new bus transaction initiator.
/// iommu: HandleValue, a handle to an IOMMU ///
/// options: u32, must be 0 (reserved for future definition of creation flags). /// `iommu: HandleValue`, a handle to an IOMMU.
/// bti_id: u64, a hardware transaction identifier for a device downstream of that IOMMU. /// `options: u32`, must be 0 (reserved for future definition of creation flags).
/// `bti_id: u64`, a hardware transaction identifier for a device downstream of that IOMMU.
pub fn sys_bti_create( pub fn sys_bti_create(
&self, &self,
iommu: HandleValue, iommu: HandleValue,
@ -68,7 +69,7 @@ impl Syscall<'_> {
} }
#[allow(clippy::too_many_arguments)] #[allow(clippy::too_many_arguments)]
/// Pin pages and grant devices access to them. /// Pin pages and grant devices access to them.
pub fn sys_bti_pin( pub fn sys_bti_pin(
&self, &self,
bti: HandleValue, bti: HandleValue,
@ -112,7 +113,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Unpins pages that were previously pinned by ```zx_bti_pin()``` /// Unpins pages that were previously pinned by `zx_bti_pin()`.
pub fn sys_pmt_unpin(&self, pmt: HandleValue) -> ZxResult { pub fn sys_pmt_unpin(&self, pmt: HandleValue) -> ZxResult {
info!("pmt.unpin: pmt={:#x}", pmt); info!("pmt.unpin: pmt={:#x}", pmt);
let proc = self.thread.proc(); let proc = self.thread.proc();
@ -121,7 +122,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// ReleaseRs all quarantined PMTs for the given BTI. /// Releases all quarantined PMTs for the given BTI.
pub fn sys_bti_release_quarantine(&self, bti: HandleValue) -> ZxResult { pub fn sys_bti_release_quarantine(&self, bti: HandleValue) -> ZxResult {
info!("bti.release_quarantine: bti = {:#x}", bti); info!("bti.release_quarantine: bti = {:#x}", bti);
let proc = self.thread.proc(); let proc = self.thread.proc();
@ -130,6 +131,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
///
pub fn sys_pc_firmware_tables( pub fn sys_pc_firmware_tables(
&self, &self,
resource: HandleValue, resource: HandleValue,
@ -176,7 +178,8 @@ impl Syscall<'_> {
} }
/// Binds or unbinds an interrupt object to a port. /// Binds or unbinds an interrupt object to a port.
/// The key used when binding the interrupt will be present in the key field of the ```zx_port_packet_t.``` ///
/// The key used when binding the interrupt will be present in the key field of the `zx_port_packet_t`.
pub fn sys_interrupt_bind( pub fn sys_interrupt_bind(
&self, &self,
interrupt: HandleValue, interrupt: HandleValue,
@ -203,7 +206,7 @@ impl Syscall<'_> {
} }
} }
/// Triggers a virtual interrupt object. /// Triggers a virtual interrupt object.
pub fn sys_interrupt_trigger( pub fn sys_interrupt_trigger(
&self, &self,
interrupt: HandleValue, interrupt: HandleValue,
@ -222,7 +225,8 @@ impl Syscall<'_> {
} }
/// Acknowledge an interrupt and re-arm it. /// Acknowledge an interrupt and re-arm it.
/// causing it to be eligible to trigger again (and delivering a packet to the port it is bound to). ///
/// This system call acknowledges an interrupt object, causing it to be eligible to trigger again (and delivering a packet to the port it is bound to).
pub fn sys_interrupt_ack(&self, interrupt: HandleValue) -> ZxResult { pub fn sys_interrupt_ack(&self, interrupt: HandleValue) -> ZxResult {
info!("interupt.ack: interrupt={:?}", interrupt); info!("interupt.ack: interrupt={:?}", interrupt);
let interrupt = self let interrupt = self
@ -232,14 +236,14 @@ impl Syscall<'_> {
interrupt.ack() interrupt.ack()
} }
/// Destroys an interrupt object. /// Destroys an interrupt object.
pub fn sys_interrupt_destroy(&self, interrupt: HandleValue) -> ZxResult { pub fn sys_interrupt_destroy(&self, interrupt: HandleValue) -> ZxResult {
info!("interupt.destory: interrupt={:?}", interrupt); info!("interupt.destory: interrupt={:?}", interrupt);
let interrupt = self.thread.proc().get_object::<Interrupt>(interrupt)?; let interrupt = self.thread.proc().get_object::<Interrupt>(interrupt)?;
interrupt.destroy() interrupt.destroy()
} }
/// A blocking syscall which causes the caller to wait until an interrupt is triggered. /// A blocking syscall which causes the caller to wait until an interrupt is triggered.
pub async fn sys_interrupt_wait( pub async fn sys_interrupt_wait(
&self, &self,
interrupt: HandleValue, interrupt: HandleValue,

7
zircon-syscall/src/debug.rs
View File

@ -2,10 +2,7 @@ use super::*;
use zircon_object::dev::*; use zircon_object::dev::*;
impl Syscall<'_> { impl Syscall<'_> {
/// Write debug info to the serial port /// Write debug info to the serial port.
/// To use the zx_debug_write() function,
/// you must specify ```kernel.enable-serial-syscalls=true``` or ```kernel.enable-serial-syscalls=output-only``` on the kernel command line.
/// Otherwise, the function returns ZX_ERR_NOT_SUPPORTED.
pub fn sys_debug_write(&self, buf: UserInPtr<u8>, len: usize) -> ZxResult { pub fn sys_debug_write(&self, buf: UserInPtr<u8>, len: usize) -> ZxResult {
info!("debug.write: buf=({:?}; {:#x})", buf, len); info!("debug.write: buf=({:?}; {:#x})", buf, len);
let data = buf.read_array(len)?; let data = buf.read_array(len)?;
@ -13,7 +10,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Read debug info from the serial port /// Read debug info from the serial port.
pub async fn sys_debug_read( pub async fn sys_debug_read(
&self, &self,
handle: HandleValue, handle: HandleValue,

6
zircon-syscall/src/debuglog.rs
View File

@ -4,7 +4,7 @@ use {
}; };
impl Syscall<'_> { impl Syscall<'_> {
/// Create a kernel managed debuglog reader or writer; /// Create a kernel managed debuglog reader or writer.
pub fn sys_debuglog_create( pub fn sys_debuglog_create(
&self, &self,
rsrc: HandleValue, rsrc: HandleValue,
@ -32,7 +32,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Write log to debuglog Kernel /// Write log entry to debuglog.
pub fn sys_debuglog_write( pub fn sys_debuglog_write(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -62,7 +62,7 @@ impl Syscall<'_> {
} }
#[allow(unsafe_code)] #[allow(unsafe_code)]
/// Read log to debuglog Kernel /// Read log entries from debuglog.
pub fn sys_debuglog_read( pub fn sys_debuglog_read(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,

10
zircon-syscall/src/exception.rs
View File

@ -52,7 +52,8 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Create a handle for the exception's thread. /// Create a handle for the exception's thread.
///
/// The exception handle out will be filled with a new handle to the exception thread. /// The exception handle out will be filled with a new handle to the exception thread.
pub fn sys_exception_get_thread( pub fn sys_exception_get_thread(
&self, &self,
@ -69,9 +70,10 @@ impl Syscall<'_> {
} }
/// Create a handle for the exception's process. /// Create a handle for the exception's process.
/// The exception handle out will be filled with a new handle to the exception process. ///
/// > Only available for job and process exception channels, /// The exception handle out will be filled with a new handle to the exception process.
/// > thread exceptions cannot access their parent process handles. /// > Only available for job and process exception channels.
/// > Thread exceptions cannot access their parent process handles.
pub fn sys_exception_get_process( pub fn sys_exception_get_process(
&self, &self,
exception: HandleValue, exception: HandleValue,

2
zircon-syscall/src/fifo.rs
View File

@ -1,7 +1,7 @@
use {super::*, zircon_object::ipc::Fifo}; use {super::*, zircon_object::ipc::Fifo};
impl Syscall<'_> { impl Syscall<'_> {
/// Creates a fifo, which is actually a pair of fifos of ```elem_count``` entries of ```elem_size``` bytes. /// Creates a fifo, which is actually a pair of fifos of `elem_count` entries of `elem_size` bytes.
pub fn sys_fifo_create( pub fn sys_fifo_create(
&self, &self,
elem_count: usize, elem_count: usize,

11
zircon-syscall/src/futex.rs
View File

@ -2,8 +2,9 @@ use {super::*, zircon_object::task::ThreadState};
impl Syscall<'_> { impl Syscall<'_> {
/// Wait on a futex. /// Wait on a futex.
/// This system call function 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``` /// This system call function 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`
pub async fn sys_futex_wait( pub async fn sys_futex_wait(
&self, &self,
value_ptr: UserInPtr<AtomicI32>, value_ptr: UserInPtr<AtomicI32>,
@ -32,7 +33,8 @@ impl Syscall<'_> {
.await?; .await?;
Ok(()) Ok(())
} }
/// Wake some waiters and requeue other waiters.
///
/// Wake some number of threads waiting on a futex, and move more waiters to another wait queue. /// Wake some number of threads waiting on a futex, and move more waiters to another wait queue.
pub fn sys_futex_requeue( pub fn sys_futex_requeue(
&self, &self,
@ -73,7 +75,8 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Wake some number of threads waiting on a futex, optionally transferring ownership to the thread which was woken in the process. /// Wake some number of threads waiting on a futex.
///
/// > Waking up zero threads is not an error condition. Passing in an unallocated address for value_ptr is not an error condition. /// > Waking up zero threads is not an error condition. Passing in an unallocated address for value_ptr is not an error condition.
pub fn sys_futex_wake(&self, value_ptr: UserInPtr<AtomicI32>, count: u32) -> ZxResult { pub fn sys_futex_wake(&self, value_ptr: UserInPtr<AtomicI32>, count: u32) -> ZxResult {
info!("futex.wake: value_ptr={:?}, count={:#x}", value_ptr, count); info!("futex.wake: value_ptr={:?}, count={:#x}", value_ptr, count);

14
zircon-syscall/src/handle.rs
View File

@ -1,8 +1,9 @@
use {super::*, core::convert::TryFrom}; use {super::*, core::convert::TryFrom};
impl Syscall<'_> { impl Syscall<'_> {
/// Creates a duplicate of handle /// Creates a duplicate of handle.
/// Referring to the same underlying object, with new access rights rights. ///
/// Referring to the same underlying object, with new access rights rights.
pub fn sys_handle_duplicate( pub fn sys_handle_duplicate(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -32,7 +33,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Close a handle and reclaim the underlying object if no other handles to it exist. /// Close a handle and reclaim the underlying object if no other handles to it exist.
pub fn sys_handle_close(&self, handle: HandleValue) -> ZxResult { pub fn sys_handle_close(&self, handle: HandleValue) -> ZxResult {
info!("handle.close: handle={:?}", handle); info!("handle.close: handle={:?}", handle);
if handle == INVALID_HANDLE { if handle == INVALID_HANDLE {
@ -43,7 +44,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Close a number of handles. /// Close a number of handles.
pub fn sys_handle_close_many( pub fn sys_handle_close_many(
&self, &self,
handles: UserInPtr<HandleValue>, handles: UserInPtr<HandleValue>,
@ -64,8 +65,9 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Creates a replacement for handle /// Creates a replacement for handle.
/// Referring to the same underlying object, with new access rights rights. ///
/// Referring to the same underlying object, with new access rights rights.
pub fn sys_handle_replace( pub fn sys_handle_replace(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,

18
zircon-syscall/src/hypervisor.rs
View File

@ -10,8 +10,9 @@ use {
}; };
impl Syscall<'_> { impl Syscall<'_> {
/// Creates a guest, which is a virtual machine that can be run within the hypervisor, /// Creates a guest virtual machine.
/// with ```vmar_handle``` used to represent the physical address space of the guest. ///
/// The guest is a virtual machine that can be run within the hypervisor, with `vmar_handle` used to represent the physical address space of the guest.
pub fn sys_guest_create( pub fn sys_guest_create(
&self, &self,
resource: HandleValue, resource: HandleValue,
@ -51,7 +52,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Sets a trap within a guest. /// Set a trap within a guest.
pub fn sys_guest_set_trap( pub fn sys_guest_set_trap(
&self, &self,
handle: HandleValue, handle: HandleValue,
@ -78,7 +79,9 @@ impl Syscall<'_> {
guest.set_trap(kind, addr as usize, size as usize, port, key) guest.set_trap(kind, addr as usize, size as usize, port, key)
} }
/// Creates a VCPU within a guest, which allows for execution within the virtual machine. /// Create a VCPU within a guest.
///
/// The VCPU allows for execution within the virtual machine.
pub fn sys_vcpu_create( pub fn sys_vcpu_create(
&self, &self,
guest_handle: HandleValue, guest_handle: HandleValue,
@ -101,7 +104,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Resume execution of a VCPU. /// Resume execution of a VCPU.
pub fn sys_vcpu_resume( pub fn sys_vcpu_resume(
&self, &self,
handle: HandleValue, handle: HandleValue,
@ -118,7 +121,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Raise an interrupt on a VCPU and may be called from any thread. /// Raise an interrupt on a VCPU and may be called from any thread.
pub fn sys_vcpu_interrupt(&self, handle: HandleValue, vector: u32) -> ZxResult { pub fn sys_vcpu_interrupt(&self, handle: HandleValue, vector: u32) -> ZxResult {
info!( info!(
"hypervisor.vcpu_interrupt: handle={:#x?}, vector={:?}", "hypervisor.vcpu_interrupt: handle={:#x?}, vector={:?}",
@ -130,7 +133,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Read the state of a VCPU. /// Read the state of a VCPU.
pub fn sys_vcpu_read_state( pub fn sys_vcpu_read_state(
&self, &self,
handle: HandleValue, handle: HandleValue,
@ -156,6 +159,7 @@ impl Syscall<'_> {
} }
/// Write the state of a VCPU. /// Write the state of a VCPU.
///
/// > It is only valid to write the state of handle when execution has been paused. /// > It is only valid to write the state of handle when execution has been paused.
pub fn sys_vcpu_write_state( pub fn sys_vcpu_write_state(
&self, &self,

28
zircon-syscall/src/object.rs
View File

@ -8,9 +8,10 @@ use {
impl Syscall<'_> { impl Syscall<'_> {
/// Ask for various properties of various kernel objects. /// Ask for various properties of various kernel objects.
/// handle_value: HandleValue, indicates the target kernel object. ///
/// property: u32, indicates which property to get/set. /// `handle_value: HandleValue`, indicates the target kernel object.
/// buffer: usize, holds the property value, and must be a pointer to a buffer of value_size bytes. /// `property: u32`, indicates which property to get/set.
/// `buffer: usize`, holds the property value, and must be a pointer to a buffer of value_size bytes.
pub fn sys_object_get_property( pub fn sys_object_get_property(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -108,7 +109,7 @@ impl Syscall<'_> {
} }
} }
/// Set various properties of various kernel objects. /// Set various properties of various kernel objects.
pub fn sys_object_set_property( pub fn sys_object_set_property(
&mut self, &mut self,
handle_value: HandleValue, handle_value: HandleValue,
@ -187,7 +188,7 @@ impl Syscall<'_> {
} }
} }
/// A blocking syscall waits for signals on an object /// A blocking syscall waits for signals on an object.
pub async fn sys_object_wait_one( pub async fn sys_object_wait_one(
&self, &self,
handle: HandleValue, handle: HandleValue,
@ -224,8 +225,9 @@ impl Syscall<'_> {
} }
/// Query information about an object. /// Query information about an object.
/// topic: u32, indicates what specific information is desired. ///
/// buffer: usize, a pointer to a buffer of size buffer_size to return the information. /// `topic: u32`, indicates what specific information is desired.
/// `buffer: usize`, a pointer to a buffer of size buffer_size to return the information.
pub fn sys_object_get_info( pub fn sys_object_get_info(
&self, &self,
handle: HandleValue, handle: HandleValue,
@ -362,7 +364,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Asserts and deasserts the userspace-accessible signal bits on the object's peer. /// Asserts and deasserts the userspace-accessible signal bits on the object's peer.
pub fn sys_object_signal_peer( pub fn sys_object_signal_peer(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -382,7 +384,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// A non-blocking syscall subscribes for signals on an object. /// A non-blocking syscall subscribes for signals on an object.
pub fn sys_object_wait_async( pub fn sys_object_wait_async(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -408,6 +410,7 @@ impl Syscall<'_> {
} }
/// Signal an object. /// Signal an object.
///
/// Asserts and deasserts the userspace-accessible signal bits on an object. /// Asserts and deasserts the userspace-accessible signal bits on an object.
pub fn sys_object_signal( pub fn sys_object_signal(
&self, &self,
@ -429,7 +432,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Wait for signals on multiple objects. /// Wait for signals on multiple objects.
pub async fn sys_object_wait_many( pub async fn sys_object_wait_many(
&self, &self,
mut user_items: UserInOutPtr<UserWaitItem>, mut user_items: UserInOutPtr<UserWaitItem>,
@ -459,8 +462,9 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Given a kernel object with children objects, /// Find the child of an object by its kid.
/// obtain a handle to the child specified by the provided kernel object id. ///
/// Given a kernel object with children objects, obtain a handle to the child specified by the provided kernel object id.
pub fn sys_object_get_child( pub fn sys_object_get_child(
&self, &self,
handle: HandleValue, handle: HandleValue,

6
zircon-syscall/src/port.rs
View File

@ -4,7 +4,7 @@ use {
}; };
impl Syscall<'_> { impl Syscall<'_> {
/// Create an IO port. /// Create an IO port.
pub fn sys_port_create(&self, options: u32, mut out: UserOutPtr<HandleValue>) -> ZxResult { pub fn sys_port_create(&self, options: u32, mut out: UserOutPtr<HandleValue>) -> ZxResult {
info!("port.create: options={:#x}", options); info!("port.create: options={:#x}", options);
let port_handle = Handle::new(Port::new(options), Rights::DEFAULT_PORT); let port_handle = Handle::new(Port::new(options), Rights::DEFAULT_PORT);
@ -13,7 +13,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Wait for a packet arrival in a port. /// Wait for a packet arrival in a port.
pub async fn sys_port_wait( pub async fn sys_port_wait(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -37,7 +37,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Queue a packet to a port. /// Queue a packet to a port.
pub fn sys_port_queue( pub fn sys_port_queue(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,

2
zircon-syscall/src/resource.rs
View File

@ -2,7 +2,7 @@ use {super::*, core::convert::TryFrom, zircon_object::dev::*};
impl Syscall<'_> { impl Syscall<'_> {
#[allow(clippy::too_many_arguments)] #[allow(clippy::too_many_arguments)]
/// Create a resource object for use with other DDK syscalls. /// Create a resource object for use with other DDK syscalls.
pub fn sys_resource_create( pub fn sys_resource_create(
&self, &self,
parent_rsrc: HandleValue, parent_rsrc: HandleValue,

10
zircon-syscall/src/signal.rs
View File

@ -6,7 +6,8 @@ use {
impl Syscall<'_> { impl Syscall<'_> {
/// Create a timer. /// Create a timer.
/// This is an object that can signal when a specified point in time has been reached ///
/// The timer is an object that can signal when a specified point in time has been reached.
pub fn sys_timer_create( pub fn sys_timer_create(
&self, &self,
options: u32, options: u32,
@ -33,7 +34,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Create an event. /// Create an event.
pub fn sys_event_create(&self, options: u32, mut out: UserOutPtr<HandleValue>) -> ZxResult { pub fn sys_event_create(&self, options: u32, mut out: UserOutPtr<HandleValue>) -> ZxResult {
info!("event.create: options={:#x}", options); info!("event.create: options={:#x}", options);
if options != 0 { if options != 0 {
@ -46,7 +47,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Create an event pair. /// Create an event pair.
pub fn sys_eventpair_create( pub fn sys_eventpair_create(
&self, &self,
options: u32, options: u32,
@ -68,6 +69,7 @@ impl Syscall<'_> {
} }
/// Start a timer. /// Start a timer.
///
/// To fire the timer immediately pass a deadline less than or equal to 0. /// To fire the timer immediately pass a deadline less than or equal to 0.
/// The slack parameter specifies a range from deadline - slack to deadline + slack during which the timer is allowed to fire. /// The slack parameter specifies a range from deadline - slack to deadline + slack during which the timer is allowed to fire.
pub fn sys_timer_set(&self, handle: HandleValue, deadline: Deadline, slack: i64) -> ZxResult { pub fn sys_timer_set(&self, handle: HandleValue, deadline: Deadline, slack: i64) -> ZxResult {
@ -84,7 +86,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Cancel a timer. /// Cancel a timer.
pub fn sys_timer_cancel(&self, handle: HandleValue) -> ZxResult { pub fn sys_timer_cancel(&self, handle: HandleValue) -> ZxResult {
info!("timer.cancel: handle={:#x}", handle); info!("timer.cancel: handle={:#x}", handle);
let proc = self.thread.proc(); let proc = self.thread.proc();

12
zircon-syscall/src/socket.rs
View File

@ -1,8 +1,9 @@
use {super::*, zircon_object::ipc::Socket, zircon_object::ipc::SocketFlags}; use {super::*, zircon_object::ipc::Socket, zircon_object::ipc::SocketFlags};
impl Syscall<'_> { impl Syscall<'_> {
/// Create a socket. /// Create a socket.
/// Socket, a connected pair of bidirectional stream transports, that can move only data, and that have a maximum capacity. ///
/// Socket is a connected pair of bidirectional stream transports, that can move only data, and that have a maximum capacity.
pub fn sys_socket_create( pub fn sys_socket_create(
&self, &self,
options: u32, options: u32,
@ -20,7 +21,8 @@ impl Syscall<'_> {
} }
/// Write data to a socket. /// Write data to a socket.
/// Attempts to write ```count: usize``` bytes to the socket specified by ```handle_value```. ///
/// Attempts to write `count: usize` bytes to the socket specified by `handle_value`.
pub fn sys_socket_write( pub fn sys_socket_write(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -48,7 +50,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Read data from a socket. /// Read data from a socket.
pub fn sys_socket_read( pub fn sys_socket_read(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -77,7 +79,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Prevent future reading or writing on a socket /// Prevent future reading or writing on a socket.
pub fn sys_socket_shutdown(&self, socket: HandleValue, options: u32) -> ZxResult { pub fn sys_socket_shutdown(&self, socket: HandleValue, options: u32) -> ZxResult {
let options = SocketFlags::from_bits_truncate(options); let options = SocketFlags::from_bits_truncate(options);
info!( info!(

16
zircon-syscall/src/stream.rs
View File

@ -1,8 +1,9 @@
use {super::*, bitflags::bitflags, zircon_object::vm::*}; use {super::*, bitflags::bitflags, zircon_object::vm::*};
impl Syscall<'_> { impl Syscall<'_> {
/// Create a stream from a VMO. /// Create a stream from a VMO.
/// For reads and writes the data in an underlying VMO. ///
/// Stream for reads and writes the data in an underlying VMO.
pub fn sys_stream_create( pub fn sys_stream_create(
&self, &self,
options: u32, options: u32,
@ -40,7 +41,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Write data to a stream at the current seek offset. /// Write data to a stream at the current seek offset.
pub fn sys_stream_writev( pub fn sys_stream_writev(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -71,7 +72,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Write data to a stream at the given offset. /// Write data to a stream at the given offset.
pub fn sys_stream_writev_at( pub fn sys_stream_writev_at(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -100,7 +101,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Read data from a stream at the current seek offset. /// Read data from a stream at the current seek offset.
pub fn sys_stream_readv( pub fn sys_stream_readv(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -127,7 +128,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Read data from a stream at the given offset. /// Read data from a stream at the given offset.
pub fn sys_stream_readv_at( pub fn sys_stream_readv_at(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -157,7 +158,8 @@ impl Syscall<'_> {
} }
/// Modify the seek offset. /// Modify the seek offset.
/// Sets the seek offset of the stream to ```offset``` relative to ```whence```. ///
/// Sets the seek offset of the stream to `offset` relative to `whence`.
pub fn sys_stream_seek( pub fn sys_stream_seek(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,

5
zircon-syscall/src/system.rs
View File

@ -6,8 +6,9 @@ use {
impl Syscall<'_> { impl Syscall<'_> {
/// Retrieve a handle to a system event. /// Retrieve a handle to a system event.
/// root_job: HandleValue, must be a handle to the root job of the system. ///
/// kind: u32, must be one of the following: /// `root_job: HandleValue`, must be a handle to the root job of the system.
/// `kind: u32`, must be one of the following:
/// ```rust /// ```rust
/// const EVENT_OUT_OF_MEMORY: u32 = 1; /// const EVENT_OUT_OF_MEMORY: u32 = 1;
/// const EVENT_MEMORY_PRESSURE_CRITICAL: u32 = 2; /// const EVENT_MEMORY_PRESSURE_CRITICAL: u32 = 2;

26
zircon-syscall/src/task.rs
View File

@ -3,6 +3,7 @@ use {super::*, zircon_object::task::*};
impl Syscall<'_> { impl Syscall<'_> {
/// Create a new process. /// Create a new process.
///
/// Upon success, handles for the new process and the root of its address space are returned. /// Upon success, handles for the new process and the root of its address space are returned.
pub fn sys_process_create( pub fn sys_process_create(
&self, &self,
@ -34,7 +35,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Exits the currently running process. /// Exits the currently running process.
pub fn sys_process_exit(&mut self, code: i64) -> ZxResult { pub fn sys_process_exit(&mut self, code: i64) -> ZxResult {
info!("proc.exit: code={:?}", code); info!("proc.exit: code={:?}", code);
let proc = self.thread.proc(); let proc = self.thread.proc();
@ -44,6 +45,7 @@ impl Syscall<'_> {
} }
/// Creates a thread within the specified process. /// Creates a thread within the specified process.
///
/// Upon success a handle for the new thread is returned. /// Upon success a handle for the new thread is returned.
pub fn sys_thread_create( pub fn sys_thread_create(
&self, &self,
@ -68,7 +70,8 @@ impl Syscall<'_> {
} }
/// Start execution on a process. /// Start execution on a process.
/// This system call is similar to ```zx_thread_start()```, but is used for the purpose of starting the first thread in a process. ///
/// This system call is similar to `zx_thread_start()`, but is used for the purpose of starting the first thread in a process.
pub fn sys_process_start( pub fn sys_process_start(
&self, &self,
proc_handle: HandleValue, proc_handle: HandleValue,
@ -101,6 +104,7 @@ impl Syscall<'_> {
} }
/// Write one aspect of thread state. /// Write one aspect of thread state.
///
/// The thread state may only be written when the thread is halted for an exception or the thread is suspended. /// The thread state may only be written when the thread is halted for an exception or the thread is suspended.
pub fn sys_thread_write_state( pub fn sys_thread_write_state(
&self, &self,
@ -122,7 +126,8 @@ impl Syscall<'_> {
} }
/// Sets process as critical to job. /// Sets process as critical to job.
/// When process terminates, job will be terminated as if ```zx_task_kill()``` was called on it. ///
/// When process terminates, job will be terminated as if `zx_task_kill()` was called on it.
pub fn sys_job_set_critical( pub fn sys_job_set_critical(
&self, &self,
job_handle: HandleValue, job_handle: HandleValue,
@ -147,7 +152,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Start execution on a thread. /// Start execution on a thread.
pub fn sys_thread_start( pub fn sys_thread_start(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -170,6 +175,7 @@ impl Syscall<'_> {
} }
/// Terminate the current running thread. /// Terminate the current running thread.
///
/// Causes the currently running thread to cease running and exit. /// Causes the currently running thread to cease running and exit.
pub fn sys_thread_exit(&mut self) -> ZxResult { pub fn sys_thread_exit(&mut self) -> ZxResult {
info!("thread.exit:"); info!("thread.exit:");
@ -179,7 +185,8 @@ impl Syscall<'_> {
} }
/// Suspend the given task. /// Suspend the given task.
/// > This function replaces task_suspend. When all callers are updated, ```zx_task_suspend()``` will be deleted and this function will be renamed ```zx_task_suspend()```. ///
/// > This function replaces task_suspend. When all callers are updated, `zx_task_suspend()` will be deleted and this function will be renamed ```zx_task_suspend()```.
pub fn sys_task_suspend_token( pub fn sys_task_suspend_token(
&self, &self,
handle: HandleValue, handle: HandleValue,
@ -241,7 +248,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// creates a new child job object given a parent job. /// Create a new child job object given a parent job.
pub fn sys_job_create( pub fn sys_job_create(
&self, &self,
parent: HandleValue, parent: HandleValue,
@ -265,7 +272,7 @@ impl Syscall<'_> {
} }
} }
/// Sets one or more security and/or resource policies to an empty job. /// Sets one or more security and/or resource policies to an empty job.
pub fn sys_job_set_policy( pub fn sys_job_set_policy(
&self, &self,
handle: HandleValue, handle: HandleValue,
@ -306,7 +313,8 @@ impl Syscall<'_> {
} }
} }
/// Read from the given process's address space. /// Read from the given process's address space.
///
/// > This function will eventually be replaced with something vmo-centric. /// > This function will eventually be replaced with something vmo-centric.
pub fn sys_process_read_memory( pub fn sys_process_read_memory(
&self, &self,
@ -329,7 +337,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Write into the given process's address space. /// Write into the given process's address space.
pub fn sys_process_write_memory( pub fn sys_process_write_memory(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,

16
zircon-syscall/src/time.rs
View File

@ -16,7 +16,7 @@ const ZX_CLOCK_UTC: u32 = 1;
const ZX_CLOCK_THREAD: u32 = 2; const ZX_CLOCK_THREAD: u32 = 2;
impl Syscall<'_> { impl Syscall<'_> {
/// Create a new clock object. /// Create a new clock object.
pub fn sys_clock_create( pub fn sys_clock_create(
&self, &self,
_options: u64, _options: u64,
@ -27,9 +27,10 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Acquire the current time. /// Acquire the current time.
/// Returns the current time of clock_id via ```time```. ///
/// Returns whether ```clock_id``` was valid. /// + Returns the current time of clock_id via `time`.
/// + Returns whether `clock_id` was valid.
pub fn sys_clock_get(&self, clock_id: u32, mut time: UserOutPtr<u64>) -> ZxResult { pub fn sys_clock_get(&self, clock_id: u32, mut time: UserOutPtr<u64>) -> ZxResult {
info!("clock.get: id={}", clock_id); info!("clock.get: id={}", clock_id);
match clock_id { match clock_id {
@ -49,7 +50,7 @@ impl Syscall<'_> {
} }
} }
/// Perform a basic read of the clock. /// Perform a basic read of the clock.
pub fn sys_clock_read(&self, handle: HandleValue, mut now: UserOutPtr<u64>) -> ZxResult { pub fn sys_clock_read(&self, handle: HandleValue, mut now: UserOutPtr<u64>) -> ZxResult {
info!("clock.read: handle={:#x?}", handle); info!("clock.read: handle={:#x?}", handle);
warn!("ignore clock handle"); warn!("ignore clock handle");
@ -87,8 +88,9 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// High resolution sleep. /// Sleep for some number of nanoseconds.
/// A ```deadline``` value less than or equal to 0 immediately yields the thread. ///
/// A `deadline` value less than or equal to 0 immediately yields the thread.
pub async fn sys_nanosleep(&self, deadline: Deadline) -> ZxResult { pub async fn sys_nanosleep(&self, deadline: Deadline) -> ZxResult {
info!("nanosleep: deadline={:?}", deadline); info!("nanosleep: deadline={:?}", deadline);
if deadline.0 <= 0 { if deadline.0 <= 0 {

15
zircon-syscall/src/vmar.rs
View File

@ -14,7 +14,8 @@ fn amount_of_alignments(options: u32) -> ZxResult<usize> {
impl Syscall<'_> { impl Syscall<'_> {
/// Allocate a new subregion. /// Allocate a new subregion.
/// Creates a new VMAR within the one specified by ```parent_vmar```. ///
/// Creates a new VMAR within the one specified by `parent_vmar`.
pub fn sys_vmar_allocate( pub fn sys_vmar_allocate(
&self, &self,
parent_vmar: HandleValue, parent_vmar: HandleValue,
@ -75,7 +76,8 @@ impl Syscall<'_> {
} }
#[allow(clippy::too_many_arguments)] #[allow(clippy::too_many_arguments)]
/// Add a memory mapping. /// Add a memory mapping.
///
/// Maps the given VMO into the given virtual memory address region. /// Maps the given VMO into the given virtual memory address region.
pub fn sys_vmar_map( pub fn sys_vmar_map(
&self, &self,
@ -162,8 +164,9 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Destroy a virtual memory address region. /// Destroy a virtual memory address region.
/// Unmaps all mappings within the given region, and destroys all sub-regions of the region. ///
/// Unmaps all mappings within the given region, and destroys all sub-regions of the region.
/// > This operation is logically recursive. /// > This operation is logically recursive.
pub fn sys_vmar_destroy(&self, handle_value: HandleValue) -> ZxResult { pub fn sys_vmar_destroy(&self, handle_value: HandleValue) -> ZxResult {
info!("vmar.destroy: handle={:?}", handle_value); info!("vmar.destroy: handle={:?}", handle_value);
@ -173,7 +176,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Set protection of virtual memory pages. /// Set protection of virtual memory pages.
pub fn sys_vmar_protect( pub fn sys_vmar_protect(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -202,7 +205,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Unmap virtual memory pages. /// Unmap virtual memory pages.
pub fn sys_vmar_unmap(&self, handle_value: HandleValue, addr: usize, len: usize) -> ZxResult { pub fn sys_vmar_unmap(&self, handle_value: HandleValue, addr: usize, len: usize) -> ZxResult {
info!( info!(
"vmar.unmap: handle_value={:#x}, addr={:#x}, len={:#x}", "vmar.unmap: handle_value={:#x}, addr={:#x}, len={:#x}",

24
zircon-syscall/src/vmo.rs
View File

@ -7,7 +7,7 @@ use {
}; };
impl Syscall<'_> { impl Syscall<'_> {
/// Create a virtual memory object(VMO). /// Create a new virtual memory object(VMO).
pub fn sys_vmo_create( pub fn sys_vmo_create(
&self, &self,
size: u64, size: u64,
@ -29,7 +29,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Read bytes from the VMO. /// Read bytes from a VMO.
pub fn sys_vmo_read( pub fn sys_vmo_read(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -54,7 +54,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Write bytes to the VMO. /// Write bytes to a VMO.
pub fn sys_vmo_write( pub fn sys_vmo_write(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -75,7 +75,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Add execute rights to a VMO. /// Add execute rights to a VMO.
pub fn sys_vmo_replace_as_executable( pub fn sys_vmo_replace_as_executable(
&self, &self,
handle: HandleValue, handle: HandleValue,
@ -102,7 +102,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Read the current size of a VMO object. /// Obtain the current size of a VMO object.
pub fn sys_vmo_get_size(&self, handle: HandleValue, mut size: UserOutPtr<usize>) -> ZxResult { pub fn sys_vmo_get_size(&self, handle: HandleValue, mut size: UserOutPtr<usize>) -> ZxResult {
info!("vmo.get_size: handle={:?}", handle); info!("vmo.get_size: handle={:?}", handle);
let proc = self.thread.proc(); let proc = self.thread.proc();
@ -111,7 +111,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Create a new virtual memory object (VMO) a child of an existing vmo. /// Create a child of an existing VMO (new virtual memory object).
pub fn sys_vmo_create_child( pub fn sys_vmo_create_child(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -175,7 +175,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Create a VM object referring to a specific contiguous range of physical memory. /// Create a VM object referring to a specific contiguous range of physical memory.
pub fn sys_vmo_create_physical( pub fn sys_vmo_create_physical(
&self, &self,
resource: HandleValue, resource: HandleValue,
@ -204,7 +204,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Create a VM object referring to a specific contiguous range of physical frame. /// Create a VM object referring to a specific contiguous range of physical frame.
pub fn sys_vmo_create_contiguous( pub fn sys_vmo_create_contiguous(
&self, &self,
bti: HandleValue, bti: HandleValue,
@ -236,7 +236,7 @@ impl Syscall<'_> {
Ok(()) Ok(())
} }
/// Resize a VMO object. /// Resize a VMO object.
pub fn sys_vmo_set_size(&self, handle_value: HandleValue, size: usize) -> ZxResult { pub fn sys_vmo_set_size(&self, handle_value: HandleValue, size: usize) -> ZxResult {
let proc = self.thread.proc(); let proc = self.thread.proc();
let vmo = proc.get_object_with_rights::<VmObject>(handle_value, Rights::WRITE)?; let vmo = proc.get_object_with_rights::<VmObject>(handle_value, Rights::WRITE)?;
@ -249,7 +249,9 @@ impl Syscall<'_> {
vmo.set_len(size) vmo.set_len(size)
} }
/// Perform an operation on a range of a VMO.performs cache and memory operations against pages held by the VMO. /// Perform an operation on a range of a VMO.
///
/// Performs cache and memory operations against pages held by the VMO.
pub fn sys_vmo_op_range( pub fn sys_vmo_op_range(
&self, &self,
handle_value: HandleValue, handle_value: HandleValue,
@ -296,7 +298,7 @@ impl Syscall<'_> {
} }
} }
/// Set the caching policy for pages held by a VMO. /// Set the caching policy for pages held by a VMO.
pub fn sys_vmo_cache_policy(&self, handle_value: HandleValue, policy: u32) -> ZxResult { pub fn sys_vmo_cache_policy(&self, handle_value: HandleValue, policy: u32) -> ZxResult {
let proc = self.thread.proc(); let proc = self.thread.proc();
let vmo = proc.get_object_with_rights::<VmObject>(handle_value, Rights::MAP)?; let vmo = proc.get_object_with_rights::<VmObject>(handle_value, Rights::MAP)?;