refactor(mm): 重命名 verify_area 为 access_ok 并改进文档 (#1597)

重命名理由：
- verify_area 暗示"已验证可访问"，具有误导性
- access_ok 强调"快速范围检查"，符合实际行为

文档改进：
- 明确说明这只是第一层检查，不保证真正可访问
- 添加粗体警告，防止误用为"已验证可访问"
- 补充典型用法示例，展示配合 copy_to_user 的正确模式

这将函数语义从"验证已完成"纠正为"可以尝试访问"，
避免开发者误认为 Ok(()) 代表地址已映射或真正可访问。

Author: mistcoversmyeyes

kernel/src/arch/x86_64/process/syscall.rs

@@ -7,7 +7,7 @@ use crate::{
         process::table::{USER_CS, USER_DS},
         MMArch,
     },
-    mm::{verify_area, MemoryManagementArch, VirtAddr},
+    mm::{access_ok, MemoryManagementArch, VirtAddr},
     process::{
         exec::{BinaryLoaderResult, ExecParam},
         ProcessControlBlock, ProcessManager,
@@ -107,7 +107,7 @@ impl Syscall {
             ARCH_SET_FS => {
                 // 验证FS地址是否为有效的用户空间地址
                 let fs_addr = VirtAddr::new(arg2);
-                verify_area(fs_addr, MMArch::PAGE_SIZE).map_err(|_| SystemError::EPERM)?;
+                access_ok(fs_addr, MMArch::PAGE_SIZE).map_err(|_| SystemError::EPERM)?;
                 arch_info.fsbase = arg2;
                 // 如果是当前进程则直接写入寄存器
                 if pcb.raw_pid() == ProcessManager::current_pcb().raw_pid() {
@@ -117,7 +117,7 @@ impl Syscall {
             ARCH_SET_GS => {
                 // 验证GS地址是否为有效的用户空间地址
                 let gs_addr = VirtAddr::new(arg2);
-                verify_area(gs_addr, MMArch::PAGE_SIZE).map_err(|_| SystemError::EPERM)?;
+                access_ok(gs_addr, MMArch::PAGE_SIZE).map_err(|_| SystemError::EPERM)?;
                 arch_info.gsbase = arg2;
                 if pcb.raw_pid() == ProcessManager::current_pcb().raw_pid() {
                     unsafe { arch_info.restore_gsbase() }

kernel/src/driver/disk/ahci/ahcidisk.rs

@@ -23,7 +23,7 @@ use crate::driver::disk::ahci::hba::{
 };
 use crate::libs::rwsem::{RwSemReadGuard, RwSemWriteGuard};
 use crate::libs::spinlock::{SpinLock, SpinLockGuard};
-use crate::mm::{verify_area, MemoryManagementArch, PhysAddr, VirtAddr};
+use crate::mm::{access_ok, MemoryManagementArch, PhysAddr, VirtAddr};
 use log::error;
 use system_error::SystemError;
 
@@ -114,7 +114,7 @@ impl AhciDisk {
         // 由于目前的内存管理机制无法把用户空间的内存地址转换为物理地址，所以只能先把数据拷贝到内核空间
         // TODO：在内存管理重构后，可以直接使用用户空间的内存地址
 
-        let user_buf = verify_area(VirtAddr::new(buf_ptr), buf.len()).is_ok();
+        let user_buf = access_ok(VirtAddr::new(buf_ptr), buf.len()).is_ok();
         let mut kbuf = if user_buf {
             let x: Vec<u8> = vec![0; buf.len()];
             Some(x)
@@ -276,7 +276,7 @@ impl AhciDisk {
 
         // 由于目前的内存管理机制无法把用户空间的内存地址转换为物理地址，所以只能先把数据拷贝到内核空间
         // TODO：在内存管理重构后，可以直接使用用户空间的内存地址
-        let user_buf = verify_area(VirtAddr::new(buf_ptr), buf.len()).is_ok();
+        let user_buf = access_ok(VirtAddr::new(buf_ptr), buf.len()).is_ok();
         let mut kbuf = if user_buf {
             let mut x: Vec<u8> = vec![0; buf.len()];
             x.resize(buf.len(), 0);

kernel/src/filesystem/vfs/iov.rs

@@ -2,7 +2,7 @@ use alloc::vec::Vec;
 use system_error::SystemError;
 
 use crate::{
-    mm::verify_area,
+    mm::access_ok,
     mm::VirtAddr,
     syscall::user_access::{
         copy_from_user_protected, user_accessible_len, UserBufferReader, UserBufferWriter,
@@ -93,7 +93,7 @@ impl IoVecs {
             // This checks that the address range is within user space limits,
             // but does NOT traverse page tables or check actual mappings.
             // Actual page mapping/permission checks happen during copy operations.
-            verify_area(base, one.iov_len)?;
+            access_ok(base, one.iov_len)?;
 
             // Skip zero-length iovecs after validation
             if one.iov_len == 0 {

kernel/src/filesystem/vfs/syscall/sys_getcwd.rs

@@ -6,7 +6,7 @@ use crate::alloc::string::ToString;
 use crate::arch::interrupt::TrapFrame;
 use crate::arch::syscall::nr::SYS_GETCWD;
 use crate::filesystem::vfs::utils::is_ancestor;
-use crate::mm::verify_area;
+use crate::mm::access_ok;
 use crate::mm::VirtAddr;
 use crate::process::ProcessManager;
 use crate::syscall::table::FormattedSyscallParam;
@@ -36,7 +36,7 @@ impl Syscall for SysGetcwdHandle {
         let size = Self::size(args);
 
         let security_check = || {
-            verify_area(VirtAddr::new(buf_vaddr as usize), size)?;
+            access_ok(VirtAddr::new(buf_vaddr as usize), size)?;
             return Ok(());
         };
         let r = security_check();

kernel/src/libs/futex/syscall/sys_futex.rs

@@ -6,7 +6,7 @@ use crate::libs::futex::{constant::*, futex::Futex};
 
 use crate::{
     arch::{interrupt::TrapFrame, syscall::nr::SYS_FUTEX},
-    mm::{verify_area, VirtAddr},
+    mm::{access_ok, VirtAddr},
     syscall::{
         table::{FormattedSyscallParam, Syscall},
         user_access::UserBufferReader,
@@ -165,7 +165,7 @@ pub(super) fn do_futex(
         | FutexArg::FUTEX_WAKE_OP
         | FutexArg::FUTEX_WAIT_REQUEUE_PI
         | FutexArg::FUTEX_CMP_REQUEUE_PI => {
-            verify_area(uaddr2, core::mem::size_of::<u32>())?;
+            access_ok(uaddr2, core::mem::size_of::<u32>())?;
         }
         _ => {}
     }
@@ -193,7 +193,7 @@ pub(super) fn do_futex(
         && uaddr.data() == 0;
 
     if !skip_uaddr_check {
-        verify_area(uaddr, core::mem::size_of::<u32>())?;
+        access_ok(uaddr, core::mem::size_of::<u32>())?;
     }
 
     match cmd {

kernel/src/libs/futex/syscall/sys_robust_futex.rs

@@ -3,7 +3,7 @@ use system_error::SystemError;
 use crate::{
     arch::interrupt::TrapFrame,
     arch::syscall::nr::{SYS_GET_ROBUST_LIST, SYS_SET_ROBUST_LIST},
-    mm::{verify_area, VirtAddr},
+    mm::{access_ok, VirtAddr},
     syscall::table::{FormattedSyscallParam, Syscall},
 };
 use alloc::{string::ToString, vec::Vec};
@@ -39,7 +39,7 @@ impl Syscall for SysSetRobustListHandle {
         let len = Self::len(args);
 
         // 判断用户空间地址的合法性
-        verify_area(head, core::mem::size_of::<u32>())?;
+        access_ok(head, core::mem::size_of::<u32>())?;
 
         let result = crate::libs::futex::futex::RobustListHead::set_robust_list(head, len);
 
@@ -99,8 +99,8 @@ impl Syscall for SysGetRobustListHandle {
         let len_ptr = Self::len_ptr(args);
 
         // 判断用户空间地址的合法性
-        verify_area(head, core::mem::size_of::<u32>())?;
-        verify_area(len_ptr, core::mem::size_of::<u32>())?;
+        access_ok(head, core::mem::size_of::<u32>())?;
+        access_ok(len_ptr, core::mem::size_of::<u32>())?;
 
         crate::libs::futex::futex::RobustListHead::get_robust_list(pid, head, len_ptr)
     }

kernel/src/mm/mod.rs

@@ -921,13 +921,31 @@ impl Ord for VirtRegion {
     }
 }
 
-/// ## 判断虚拟地址是否超出了用户空间
+/// ## 快速检查用户地址范围的基本合法性
 ///
-/// 如果虚拟地址超出了用户空间，返回Err(SystemError::EFAULT).
-/// 如果end < start，返回Err(SystemError::EOVERFLOW)
+/// 该函数是**第一层检查**，仅验证地址是否在用户空间范围内，
+/// 以及是否发生算术溢出。**不保证地址真正可访问**。
 ///
-/// 否则返回Ok(())
-pub fn verify_area(addr: VirtAddr, size: usize) -> Result<(), SystemError> {
+/// ⚠️ **重要**: 返回 `Ok(())` 不意味着地址已映射或真正可访问。
+/// 实际访问时仍可能触发缺页异常。
+///
+/// ### 参数
+/// - `addr`: 起始虚拟地址
+/// - `size`: 要检查的字节数
+///
+/// ### 返回值
+/// - `Ok(())`: 地址范围看起来合法，**可以尝试访问**
+/// - `Err(SystemError::EFAULT)`: 地址不在用户空间
+/// - `Err(SystemError::EOVERFLOW)`: `addr + size` 溢出
+///
+/// ### 典型用法
+/// ```rust
+/// // 作为快速失败的前置检查
+/// if access_ok(user_ptr, size).is_ok() {
+///     copy_to_user(user_ptr, data, size)?;  // 真正的访问（带缺页处理）
+/// }
+/// ```
+pub fn access_ok(addr: VirtAddr, size: usize) -> Result<(), SystemError> {
     let end = addr.add(size);
     if unlikely(end.data() < addr.data()) {
         return Err(SystemError::EOVERFLOW);

kernel/src/mm/syscall/sys_madvise.rs

@@ -5,7 +5,7 @@ use crate::libs::align::page_align_up;
 use crate::mm::{
     syscall::{MadvFlags, PageFrameCount},
     ucontext::AddressSpace,
-    MemoryManagementArch, VirtPageFrame, {verify_area, VirtAddr},
+    MemoryManagementArch, VirtPageFrame, {access_ok, VirtAddr},
 };
 use crate::syscall::table::{FormattedSyscallParam, Syscall};
 use system_error::SystemError;
@@ -62,7 +62,7 @@ impl Syscall for SysMadviseHandle {
         }
 
         // 验证地址范围的有效性
-        if verify_area(start_vaddr, aligned_len).is_err() {
+        if access_ok(start_vaddr, aligned_len).is_err() {
             return Err(SystemError::EINVAL);
         }
 

kernel/src/mm/syscall/sys_mincore.rs

@@ -4,7 +4,7 @@ use crate::arch::MMArch;
 use crate::libs::align::page_align_up;
 use crate::mm::allocator::page_frame::{PageFrameCount, VirtPageFrame};
 use crate::mm::ucontext::AddressSpace;
-use crate::mm::{verify_area, MemoryManagementArch};
+use crate::mm::{access_ok, MemoryManagementArch};
 use crate::syscall::table::{FormattedSyscallParam, Syscall};
 use crate::syscall::user_access::UserBufferWriter;
 use system_error::SystemError;
@@ -35,7 +35,7 @@ impl Syscall for SysMincoreHandle {
             return Err(SystemError::EINVAL);
         }
 
-        if verify_area(start_vaddr, len).is_err() {
+        if access_ok(start_vaddr, len).is_err() {
             return Err(SystemError::ENOMEM);
         }
         if len == 0 {

kernel/src/mm/syscall/sys_mmap.rs

@@ -7,7 +7,7 @@ use crate::mm::syscall::MapFlags;
 use crate::mm::ucontext::DEFAULT_MMAP_MIN_ADDR;
 use crate::mm::AddressSpace;
 use crate::mm::VirtAddr;
-use crate::mm::{verify_area, MemoryManagementArch};
+use crate::mm::{access_ok, MemoryManagementArch};
 use crate::syscall::table::{FormattedSyscallParam, Syscall};
 use log::error;
 use system_error::SystemError;
@@ -60,7 +60,7 @@ impl Syscall for SysMmapHandle {
         }
         let offset = offset_raw as usize;
         // 基础参数校验
-        if verify_area(start_vaddr, len).is_err() {
+        if access_ok(start_vaddr, len).is_err() {
             return Err(SystemError::EFAULT);
         }