From d1b429ed03e984b8d7ed1136db085dd48326ef32 Mon Sep 17 00:00:00 2001
From: Dongyan Qian <qiandongyan@loongson.cn>
Date: Wed, 1 Apr 2026 11:45:56 +0800
Subject: [PATCH 1/2] Document iomem=relaxed requirement for MMIO access

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index 85090ad..05bd1df 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,7 @@ flowchart TB
 - 需预装 gcc、make
 - Python 环境（部分脚本功能可选）
 - 部分命令需 root 权限
+- 部分直接访问物理地址 / MMIO / SPI 控制器寄存器的命令，可能还需要在内核启动参数中启用 `iomem=relaxed`；否则 `/dev/mem` 访问或内存映射可能被内核拒绝
 
 ### 依赖
 
@@ -121,6 +122,8 @@ Arguments:
     -c, --count <int>     read count (读取长度)
 ```
 
+如果执行 `gpio`、`spi`、`conf` 或其他直接访问物理寄存器的命令时出现 `/dev/mem` 打开失败、`mmap` 失败，或访问被拒绝等错误，请检查当前内核命令行是否允许原始 I/O 内存访问。某些平台需要额外启用 `iomem=relaxed` 才能正常使用这些命令。
+
 ### 固件更新/备份示例
 
 - **更新主板固件**  

From e2178010b2cfe433ea5bc920a413690f90cd721f Mon Sep 17 00:00:00 2001
From: Dongyan Qian <qiandongyan@loongson.cn>
Date: Wed, 1 Apr 2026 11:45:58 +0800
Subject: [PATCH 2/2] Warn when MMIO mapping may need iomem=relaxed

---
 LoongArch/util.c | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/LoongArch/util.c b/LoongArch/util.c
index 949ba04..e4d4512 100644
--- a/LoongArch/util.c
+++ b/LoongArch/util.c
@@ -14,6 +14,11 @@
 #define MAC_ADDRESS_LEN 6		/* mac地址长为6位十六进制数*/
 typedef int bool;
 
+static void print_iomem_relaxed_hint(void)
+{
+    printf("Hint: raw physical/MMIO access may require enabling iomem=relaxed in the kernel command line.\n");
+}
+
 static unsigned long long memmask;
 static int memoffset;
 uchar aucResMac[MAC_ADDRESS_LEN+1]={0};
@@ -152,6 +157,11 @@ void *vtpa(unsigned long long vaddr,int fd)
     memmask = vaddr & ~(0xffff);
     memoffset = vaddr & (0xffff);
     p = (void*)mmap(NULL,0x10000/*64K*/, PROT_READ|PROT_WRITE,MAP_SHARED,fd,memmask);
+    if (p == MAP_FAILED) {
+        printf("mmap failed for physical address 0x%llx\n", vaddr);
+        print_iomem_relaxed_hint();
+        return NULL;
+    }
     p = p + memoffset;
     printf("mmap addr start : %p \n",p);
     return p;