oak_tests: add safety sections to doc comments
@@ -72,8 +72,12 @@ extern "C" {
pub fn oak_main(handle: u64) -> i32;
}
-/// Test implementation of channel wait functionality, which always indicates
-/// that all provided channels are ready for reading.
+/// Test implementation of channel wait functionality.
+///
+/// # Safety
+///
+/// The linear memory range [buf, buf+count*SPACE_BYTES_PER_HANDLE) must be
+/// valid.
#[no_mangle]
pub unsafe extern "C" fn wait_on_channels(buf: *mut u8, count: u32) -> u32 {
let name = node_name();
@@ -139,6 +143,11 @@ pub unsafe extern "C" fn wait_on_channels(buf: *mut u8, count: u32) -> u32 {
}
/// Test-only implementation of channel write functionality.
+///
+/// # Safety
+///
+/// The linear memory ranges [buf, buf+size) and [handle_buf, handle_buf+handle_count*8) must be
+/// valid.
#[no_mangle]
pub unsafe extern "C" fn channel_write(
handle: u64,
@@ -185,8 +194,12 @@ pub unsafe extern "C" fn channel_write(
result
}
-/// Test implementation of channel read functionality, which reads a message
-/// from the test channel.
+/// Test implementation of channel read functionality.
+///
+/// # Safety
+///
+/// The linear memory ranges [buf, buf+size) and [handle_buf, handle_buf+handle_count*8) must be
+/// valid, as must the raw pointers actual_size and actual_handle_count.
#[no_mangle]
pub unsafe extern "C" fn channel_read(
handle: u64,
@@ -240,6 +253,10 @@ pub unsafe extern "C" fn channel_read(
}
/// Test version of channel creation.
+///
+/// # Safety
+///
+/// The raw pointers to linear memory must be valid.
#[no_mangle]
pub unsafe extern "C" fn channel_create(write: *mut u64, read: *mut u64) -> u32 {
let name = node_name();
@@ -272,6 +289,10 @@ pub extern "C" fn channel_close(handle: u64) -> u32 {
}
/// Test implementation of dynamic Node creation.
+///
+/// # Safety
+///
+/// The linear memory range [buf, buf+len) must be valid.
#[no_mangle]
pub unsafe fn node_create(buf: *const u8, len: usize, handle: u64) -> u32 {
let name = node_name();
@@ -312,6 +333,10 @@ pub unsafe fn node_create(buf: *const u8, len: usize, handle: u64) -> u32 {
}
/// Test version of random data generation.
+///
+/// # Safety
+///
+/// The linear memory range [buf, buf+size) must be valid.
#[no_mangle]
pub unsafe extern "C" fn random_get(buf: *mut u8, size: usize) -> u32 {
let name = node_name();
