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

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

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

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

@ -1,13 +1,16 @@
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<'_> {
/// 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 {
info!("cprng_draw_once: buf=({:?}; {:?})", buf, 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)?;
Ok(())
}

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

@ -39,9 +39,10 @@ impl Syscall<'_> {
Ok(())
}
/// 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).
/// bti_id: u64, a hardware transaction identifier for a device downstream of that IOMMU.
///
/// `iommu: HandleValue`, a handle to an 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(
&self,
iommu: HandleValue,
@ -112,7 +113,7 @@ impl Syscall<'_> {
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 {
info!("pmt.unpin: pmt={:#x}", pmt);
let proc = self.thread.proc();
@ -121,7 +122,7 @@ impl Syscall<'_> {
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 {
info!("bti.release_quarantine: bti = {:#x}", bti);
let proc = self.thread.proc();
@ -130,6 +131,7 @@ impl Syscall<'_> {
Ok(())
}
///
pub fn sys_pc_firmware_tables(
&self,
resource: HandleValue,
@ -176,7 +178,8 @@ impl Syscall<'_> {
}
/// 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(
&self,
interrupt: HandleValue,
@ -222,7 +225,8 @@ impl Syscall<'_> {
}
/// 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 {
info!("interupt.ack: interrupt={:?}", interrupt);
let interrupt = self

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

@ -2,10 +2,7 @@ use super::*;
use zircon_object::dev::*;
impl Syscall<'_> {
/// 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.
/// Write debug info to the serial port.
pub fn sys_debug_write(&self, buf: UserInPtr<u8>, len: usize) -> ZxResult {
info!("debug.write: buf=({:?}; {:#x})", buf, len);
let data = buf.read_array(len)?;
@ -13,7 +10,7 @@ impl Syscall<'_> {
Ok(())
}
/// Read debug info from the serial port
/// Read debug info from the serial port.
pub async fn sys_debug_read(
&self,
handle: HandleValue,

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

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

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

@ -53,6 +53,7 @@ impl Syscall<'_> {
}
/// Create a handle for the exception's thread.
///
/// The exception handle out will be filled with a new handle to the exception thread.
pub fn sys_exception_get_thread(
&self,
@ -69,9 +70,10 @@ impl Syscall<'_> {
}
/// 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,
/// > 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(
&self,
exception: HandleValue,

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

@ -1,7 +1,7 @@
use {super::*, zircon_object::ipc::Fifo};
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(
&self,
elem_count: usize,

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

@ -2,8 +2,9 @@ use {super::*, zircon_object::task::ThreadState};
impl Syscall<'_> {
/// 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(
&self,
value_ptr: UserInPtr<AtomicI32>,
@ -32,7 +33,8 @@ impl Syscall<'_> {
.await?;
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.
pub fn sys_futex_requeue(
&self,
@ -73,7 +75,8 @@ impl Syscall<'_> {
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.
pub fn sys_futex_wake(&self, value_ptr: UserInPtr<AtomicI32>, count: u32) -> ZxResult {
info!("futex.wake: value_ptr={:?}, count={:#x}", value_ptr, count);

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

@ -1,7 +1,8 @@
use {super::*, core::convert::TryFrom};
impl Syscall<'_> {
/// Creates a duplicate of handle
/// Creates a duplicate of handle.
///
/// Referring to the same underlying object, with new access rights rights.
pub fn sys_handle_duplicate(
&self,
@ -64,7 +65,8 @@ impl Syscall<'_> {
Ok(())
}
/// Creates a replacement for handle
/// Creates a replacement for handle.
///
/// Referring to the same underlying object, with new access rights rights.
pub fn sys_handle_replace(
&self,

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

@ -10,8 +10,9 @@ use {
};
impl Syscall<'_> {
/// Creates a guest, which is a virtual machine that can be run within the hypervisor,
/// with ```vmar_handle``` used to represent the physical address space of the guest.
/// Creates a guest virtual machine.
///
/// 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(
&self,
resource: HandleValue,
@ -51,7 +52,7 @@ impl Syscall<'_> {
Ok(())
}
/// Sets a trap within a guest.
/// Set a trap within a guest.
pub fn sys_guest_set_trap(
&self,
handle: HandleValue,
@ -78,7 +79,9 @@ impl Syscall<'_> {
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(
&self,
guest_handle: HandleValue,
@ -156,6 +159,7 @@ impl Syscall<'_> {
}
/// Write the state of a VCPU.
///
/// > It is only valid to write the state of handle when execution has been paused.
pub fn sys_vcpu_write_state(
&self,

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

@ -8,9 +8,10 @@ use {
impl Syscall<'_> {
/// Ask for various properties of various kernel objects.
/// handle_value: HandleValue, indicates the target kernel object.
/// 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.
///
/// `handle_value: HandleValue`, indicates the target kernel object.
/// `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(
&self,
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(
&self,
handle: HandleValue,
@ -224,8 +225,9 @@ impl Syscall<'_> {
}
/// 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(
&self,
handle: HandleValue,
@ -408,6 +410,7 @@ impl Syscall<'_> {
}
/// Signal an object.
///
/// Asserts and deasserts the userspace-accessible signal bits on an object.
pub fn sys_object_signal(
&self,
@ -459,8 +462,9 @@ impl Syscall<'_> {
Ok(())
}
/// Given a kernel object with children objects,
/// obtain a handle to the child specified by the provided kernel object id.
/// Find the child of an object by its kid.
///
/// 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(
&self,
handle: HandleValue,

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

@ -6,7 +6,8 @@ use {
impl Syscall<'_> {
/// 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(
&self,
options: u32,
@ -68,6 +69,7 @@ impl Syscall<'_> {
}
/// Start a timer.
///
/// 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.
pub fn sys_timer_set(&self, handle: HandleValue, deadline: Deadline, slack: i64) -> ZxResult {

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

@ -2,7 +2,8 @@ use {super::*, zircon_object::ipc::Socket, zircon_object::ipc::SocketFlags};
impl Syscall<'_> {
/// 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(
&self,
options: u32,
@ -20,7 +21,8 @@ impl Syscall<'_> {
}
/// 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(
&self,
handle_value: HandleValue,
@ -77,7 +79,7 @@ impl Syscall<'_> {
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 {
let options = SocketFlags::from_bits_truncate(options);
info!(

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

@ -2,7 +2,8 @@ use {super::*, bitflags::bitflags, zircon_object::vm::*};
impl Syscall<'_> {
/// 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(
&self,
options: u32,
@ -157,7 +158,8 @@ impl Syscall<'_> {
}
/// 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(
&self,
handle_value: HandleValue,

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

@ -6,8 +6,9 @@ use {
impl Syscall<'_> {
/// 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
/// const EVENT_OUT_OF_MEMORY: u32 = 1;
/// const EVENT_MEMORY_PRESSURE_CRITICAL: u32 = 2;

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

@ -3,6 +3,7 @@ use {super::*, zircon_object::task::*};
impl Syscall<'_> {
/// Create a new process.
///
/// Upon success, handles for the new process and the root of its address space are returned.
pub fn sys_process_create(
&self,
@ -44,6 +45,7 @@ impl Syscall<'_> {
}
/// Creates a thread within the specified process.
///
/// Upon success a handle for the new thread is returned.
pub fn sys_thread_create(
&self,
@ -68,7 +70,8 @@ impl Syscall<'_> {
}
/// 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(
&self,
proc_handle: HandleValue,
@ -101,6 +104,7 @@ impl Syscall<'_> {
}
/// 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.
pub fn sys_thread_write_state(
&self,
@ -122,7 +126,8 @@ impl Syscall<'_> {
}
/// 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(
&self,
job_handle: HandleValue,
@ -170,6 +175,7 @@ impl Syscall<'_> {
}
/// Terminate the current running thread.
///
/// Causes the currently running thread to cease running and exit.
pub fn sys_thread_exit(&mut self) -> ZxResult {
info!("thread.exit:");
@ -179,7 +185,8 @@ impl Syscall<'_> {
}
/// 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(
&self,
handle: HandleValue,
@ -241,7 +248,7 @@ impl Syscall<'_> {
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(
&self,
parent: HandleValue,
@ -307,6 +314,7 @@ impl Syscall<'_> {
}
/// Read from the given process's address space.
///
/// > This function will eventually be replaced with something vmo-centric.
pub fn sys_process_read_memory(
&self,

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

@ -28,8 +28,9 @@ impl Syscall<'_> {
}
/// 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 {
info!("clock.get: id={}", clock_id);
match clock_id {
@ -87,8 +88,9 @@ impl Syscall<'_> {
Ok(())
}
/// High resolution sleep.
/// A ```deadline``` value less than or equal to 0 immediately yields the thread.
/// Sleep for some number of nanoseconds.
///
/// A `deadline` value less than or equal to 0 immediately yields the thread.
pub async fn sys_nanosleep(&self, deadline: Deadline) -> ZxResult {
info!("nanosleep: deadline={:?}", deadline);
if deadline.0 <= 0 {

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

@ -14,7 +14,8 @@ fn amount_of_alignments(options: u32) -> ZxResult<usize> {
impl Syscall<'_> {
/// 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(
&self,
parent_vmar: HandleValue,
@ -76,6 +77,7 @@ impl Syscall<'_> {
#[allow(clippy::too_many_arguments)]
/// Add a memory mapping.
///
/// Maps the given VMO into the given virtual memory address region.
pub fn sys_vmar_map(
&self,
@ -163,6 +165,7 @@ impl Syscall<'_> {
}
/// Destroy a virtual memory address region.
///
/// Unmaps all mappings within the given region, and destroys all sub-regions of the region.
/// > This operation is logically recursive.
pub fn sys_vmar_destroy(&self, handle_value: HandleValue) -> ZxResult {

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

@ -7,7 +7,7 @@ use {
};
impl Syscall<'_> {
/// Create a virtual memory object(VMO).
/// Create a new virtual memory object(VMO).
pub fn sys_vmo_create(
&self,
size: u64,
@ -29,7 +29,7 @@ impl Syscall<'_> {
Ok(())
}
/// Read bytes from the VMO.
/// Read bytes from a VMO.
pub fn sys_vmo_read(
&self,
handle_value: HandleValue,
@ -54,7 +54,7 @@ impl Syscall<'_> {
Ok(())
}
/// Write bytes to the VMO.
/// Write bytes to a VMO.
pub fn sys_vmo_write(
&self,
handle_value: HandleValue,
@ -102,7 +102,7 @@ impl Syscall<'_> {
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 {
info!("vmo.get_size: handle={:?}", handle);
let proc = self.thread.proc();
@ -111,7 +111,7 @@ impl Syscall<'_> {
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(
&self,
handle_value: HandleValue,
@ -249,7 +249,9 @@ impl Syscall<'_> {
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(
&self,
handle_value: HandleValue,