Skip to content

Commit 37039fd

Browse files
committed
Add Safety section to docs of unsafe functions
1 parent 5d1f121 commit 37039fd

File tree

7 files changed

+62
-1
lines changed

7 files changed

+62
-1
lines changed

src/data_types/strs.rs

+22
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,12 @@ pub struct CStr8([Char8]);
2424

2525
impl CStr8 {
2626
/// Wraps a raw UEFI string with a safe C string wrapper
27+
///
28+
/// # Safety
29+
///
30+
/// The function will start accessing memory from `ptr` until the first
31+
/// null byte. It's the callers responsability to ensure `ptr` points to
32+
/// a valid string, in accessible memory.
2733
pub unsafe fn from_ptr<'ptr>(ptr: *const Char8) -> &'ptr Self {
2834
let mut len = 0;
2935
while *ptr.add(len) != NUL_8 {
@@ -47,6 +53,11 @@ impl CStr8 {
4753
}
4854

4955
/// Unsafely creates a C string wrapper from bytes
56+
///
57+
/// # Safety
58+
///
59+
/// It's the callers responsability to ensure chars is a valid Latin-1
60+
/// null-terminated string, with no interior null bytes.
5061
pub unsafe fn from_bytes_with_nul_unchecked(chars: &[u8]) -> &Self {
5162
&*(chars as *const [u8] as *const Self)
5263
}
@@ -77,6 +88,12 @@ pub struct CStr16([Char16]);
7788

7889
impl CStr16 {
7990
/// Wraps a raw UEFI string with a safe C string wrapper
91+
///
92+
/// # Safety
93+
///
94+
/// The function will start accessing memory from `ptr` until the first
95+
/// null byte. It's the callers responsability to ensure `ptr` points to
96+
/// a valid string, in accessible memory.
8097
pub unsafe fn from_ptr<'ptr>(ptr: *const Char16) -> &'ptr Self {
8198
let mut len = 0;
8299
while *ptr.add(len) != NUL_16 {
@@ -110,6 +127,11 @@ impl CStr16 {
110127
}
111128

112129
/// Unsafely creates a C string wrapper from a u16 slice.
130+
///
131+
/// # Safety
132+
///
133+
/// It's the callers responsability to ensure chars is a valid UCS-2
134+
/// null-terminated string, with no interior null bytes.
113135
pub unsafe fn from_u16_with_nul_unchecked(codes: &[u16]) -> &Self {
114136
&*(codes as *const [u16] as *const Self)
115137
}

src/logger.rs

+5
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,11 @@ impl Logger {
3131
///
3232
/// You must arrange for the `disable` method to be called or for this logger
3333
/// to be otherwise discarded before boot services are exited.
34+
///
35+
/// # Safety
36+
///
37+
/// Undefined behaviour may occur if this logger is still active after the
38+
/// application has exited the boot services stage.
3439
pub unsafe fn new(output: &mut Output) -> Self {
3540
Logger {
3641
writer: NonNull::new(output as *const _ as *mut _),

src/proto/console/gop.rs

+8
Original file line numberDiff line numberDiff line change
@@ -550,6 +550,8 @@ impl<'gop> FrameBuffer<'gop> {
550550

551551
/// Modify the i-th byte of the frame buffer
552552
///
553+
/// # Safety
554+
///
553555
/// This operation is unsafe because...
554556
/// - You must honor the pixel format and stride specified by the mode info
555557
/// - There is no bound checking on memory accesses in release mode
@@ -561,6 +563,8 @@ impl<'gop> FrameBuffer<'gop> {
561563

562564
/// Read the i-th byte of the frame buffer
563565
///
566+
/// # Safety
567+
///
564568
/// This operation is unsafe because...
565569
/// - You must honor the pixel format and stride specified by the mode info
566570
/// - There is no bound checking on memory accesses in release mode
@@ -576,6 +580,8 @@ impl<'gop> FrameBuffer<'gop> {
576580
/// const generics, it will be deprecated and replaced with a write_bytes()
577581
/// method that only accepts [u8; N] input.
578582
///
583+
/// # Safety
584+
///
579585
/// This operation is unsafe because...
580586
/// - It is your reponsibility to make sure that the value type makes sense
581587
/// - You must honor the pixel format and stride specified by the mode info
@@ -595,6 +601,8 @@ impl<'gop> FrameBuffer<'gop> {
595601
/// const generics, it will be deprecated and replaced with a read_bytes()
596602
/// method that only accepts [u8; N] input.
597603
///
604+
/// # Safety
605+
///
598606
/// This operation is unsafe because...
599607
/// - It is your reponsibility to make sure that the value type makes sense
600608
/// - You must honor the pixel format and stride specified by the mode info

src/proto/media/file/info.rs

+5
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,11 @@ pub trait FileProtocolInfo: Align + Identify + FromUefi {}
2121
/// the fat pointer must be reconstructed using hidden UEFI-provided metadata.
2222
pub trait FromUefi {
2323
/// Turn an UEFI-provided pointer-to-base into a (possibly fat) Rust reference
24+
///
25+
/// # Safety
26+
///
27+
/// This function can lead to undefined behavior if the given pointer is not
28+
/// pointing to a valid object of the specified type.
2429
unsafe fn from_uefi<'ptr>(ptr: *mut c_void) -> &'ptr mut Self;
2530
}
2631

src/table/boot.rs

+12
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,12 @@ impl BootServices {
134134
///
135135
/// This function outputs an RAII guard that will automatically restore the
136136
/// original `Tpl` when dropped.
137+
///
138+
/// # Safety
139+
///
140+
/// Raising a task's priority level can affect other running tasks and
141+
/// critical processes run by UEFI. The highest priority level is the
142+
/// most dangerous, since it disables interrupts.
137143
pub unsafe fn raise_tpl(&self, tpl: Tpl) -> TplGuard<'_> {
138144
TplGuard {
139145
boot_services: self,
@@ -260,6 +266,8 @@ impl BootServices {
260266
/// will be delivered next time `wait_for_event` or `check_event` is called.
261267
/// In both cases, a `notify_fn` callback must be specified.
262268
///
269+
/// # Safety
270+
///
263271
/// This function is unsafe because callbacks must handle exit from boot
264272
/// services correctly.
265273
pub unsafe fn create_event(
@@ -472,6 +480,8 @@ impl BootServices {
472480

473481
/// Copies memory from source to destination. The buffers can overlap.
474482
///
483+
/// # Safety
484+
///
475485
/// This function is unsafe as it can be used to violate most safety
476486
/// invariants of the Rust type system.
477487
pub unsafe fn memmove(&self, dest: *mut u8, src: *const u8, size: usize) {
@@ -480,6 +490,8 @@ impl BootServices {
480490

481491
/// Sets a buffer to a certain value.
482492
///
493+
/// # Safety
494+
///
483495
/// This function is unsafe as it can be used to violate most safety
484496
/// invariants of the Rust type system.
485497
pub unsafe fn memset(&self, buffer: *mut u8, size: usize, value: u8) {

src/table/runtime.rs

+6-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,12 @@ impl RuntimeServices {
4545
/// Sets the current local time and date information
4646
///
4747
/// During runtime, if a PC-AT CMOS device is present in the platform, the
48-
/// caller must synchronize access to the device before calling set_time.
48+
/// caller must synchronize access to the device before calling `set_time`.
49+
///
50+
/// # Safety
51+
///
52+
/// Undefined behavior could happen if multiple tasks try to
53+
/// use this function at the same time without synchronisation.
4954
pub unsafe fn set_time(&mut self, time: &Time) -> Result {
5055
(self.set_time)(time).into()
5156
}

src/table/system.rs

+4
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,8 @@ impl SystemTable<Boot> {
170170

171171
/// Clone this boot-time UEFI system table interface
172172
///
173+
/// # Safety
174+
///
173175
/// This is unsafe because you must guarantee that the clone will not be
174176
/// used after boot services are exited. However, the singleton-based
175177
/// designs that Rust uses for memory allocation, logging, and panic
@@ -187,6 +189,8 @@ impl SystemTable<Boot> {
187189
impl SystemTable<Runtime> {
188190
/// Access runtime services
189191
///
192+
/// # Safety
193+
///
190194
/// This is unsafe because UEFI runtime services require an elaborate
191195
/// CPU configuration which may not be preserved by OS loaders. See the
192196
/// "Calling Conventions" chapter of the UEFI specification for details.

0 commit comments

Comments
 (0)