WikiBot: Fix repository links: point to the cgit tree URLs

2026-10-12T04:41:02Z

Fix repository links: point to the cgit tree URLs

← Older revision		Revision as of 04:41, 12 October 2026
Line 3:		Line 3:
	= WPR (Write/Read Protect Region) Management =		= WPR (Write/Read Protect Region) Management =

	<blockquote>'''Historical document — superseded.''' WPR is the '''write-protected region of VRAM reserved for firmware''', not a generic read/write-protect mechanism; the read-protect framing below is historical reverse-engineering material. Canonical documentation: [https://git.vgpu.io/open-iov/~~blob/master~~/docs/03-architecture/06-host-module-and-hybrid-model.md <code>../docs/03-architecture/06-host-module-and-hybrid-model.md</code>].</blockquote>		<blockquote>'''Historical document — superseded.''' WPR is the '''write-protected region of VRAM reserved for firmware''', not a generic read/write-protect mechanism; the read-protect framing below is historical reverse-engineering material. Canonical documentation: [https://git.vgpu.io/open-iov.git/tree/docs/03-architecture/06-host-module-and-hybrid-model.md <code>../docs/03-architecture/06-host-module-and-hybrid-model.md</code>].</blockquote>

	== Overview ==		== Overview ==

WikiBot: Carry the site-wide About/licensing message on every page (2026-10-12)

2026-10-12T04:29:53Z

Carry the site-wide About/licensing message on every page (2026-10-12)

← Older revision		Revision as of 04:29, 12 October 2026
Line 1:		Line 1:
			{{About message}}

	= WPR (Write/Read Protect Region) Management =		= WPR (Write/Read Protect Region) Management =

WikiBot: Re-sync page from tracked wiki source: fix cross-document links and diagram; refresh status

2026-10-12T04:10:06Z

Re-sync page from tracked wiki source: fix cross-document links and diagram; refresh status

Show changes

WikiBot: Remove unpaired blockquote tags left by reference cleanup

2026-10-12T03:58:31Z

Remove unpaired blockquote tags left by reference cleanup

New page

= WPR (Write/Read Protect Region) Management =


== Overview ==

WPR (Write Protect Region / Read Protect Region) provides memory isolation for vGPU by protecting guest memory regions from unauthorized access. The GSP firmware implements WPR through two handlers at '''0x04F00B0C''' and '''0x04F00C78''' (62 KB each).

== Key Addresses ==

{| class="wikitable"
|-
! Handler
! Address
! Size
! Role
|-
| WPR Handler 1
| 0x04F00B0C
| 62 KB
| Primary WPR management
|-
| WPR Handler 2
| 0x04F00C78
| 62 KB
| Secondary/timeout handling
|-
| String Table
| 60 locations
| —
| Completion/timeout strings
|}


== String References (60 Total) ==


=== Completion Events ===

<pre>WPR_WRITE_COMPLETE 0x5E478F8
WPR_READ_COMPLETE 0x5E478E0
NV_WPR_WRITE_COMPLETE 0x5E478C8
NV_WPR_READ_COMPLETE 0x5E478B0</pre>

=== Timeout Events ===

<pre>WPR_WRITE_TIMEOUT 0x5E47898
WPR_READ_TIMEOUT 0x5E47880
NV_WPR_WRITE_TIMEOUT 0x5E47868
NV_WPR_READ_TIMEOUT 0x5E47850</pre>

== WPR State Machine ==


=== Handler 1: 0x04F00B0C (Primary) ===

<syntaxhighlight lang="c">typedef enum {
WPR_STATE_IDLE = 0,
WPR_STATE_WRITE_PENDING = 1,
WPR_STATE_READ_PENDING = 2,
WPR_STATE_COMPLETE = 3,
WPR_STATE_TIMEOUT = 4,
WPR_STATE_ERROR = 0xFFFF
} wpr_state_t;

typedef struct {
uint64_t region_base; // Protected region base
uint64_t region_size; // Region size (page-aligned)
uint32_t vf_id; // Owning VF
uint32_t flags; // WPR_WRITE | WPR_READ | WPR_EXECUTE
wpr_state_t state;
uint64_t timeout_ns; // Operation timeout
void *completion_cb; // Callback on complete
void *timeout_cb; // Callback on timeout
} wpr_region_t;</syntaxhighlight>

=== Operation Flow ===


==== Write Protect ====

<pre>1. VF requests WPR_WRITE on region [base, base+size)
2. Handler validates alignment (4KB) and permissions
3. Programs MMU/IOMMU write-protect bits
4. Starts timeout timer (configurable)
5. On GPU write attempt:
a. Trap to GSP via page fault
b. Check if VF owns region
c. If allowed: emulate write, return OK
d. If denied: trigger WPR_WRITE_COMPLETE/NV_WPR_WRITE_COMPLETE
6. On timeout: trigger WPR_WRITE_TIMEOUT/NV_WPR_WRITE_TIMEOUT</pre>

==== Read Protect ====

<pre>1. VF requests WPR_READ on region
2. Programs MMU/IOMMU read-protect bits
3. On GPU read attempt:
a. Trap to GSP
b. Return zero/poison data or emulate
c. Trigger WPR_READ_COMPLETE/NV_WPR_READ_COMPLETE
4. On timeout: trigger WPR_READ_TIMEOUT/NV_WPR_READ_TIMEOUT</pre>

== VBIOS Parsing (Handler 2: 0x04F00C78) ==

The WPR handlers parse VBIOS structures for legacy compatibility:

<syntaxhighlight lang="c">int parse_vbios_for_wpr(void *vbios_ptr, size_t size) {
// Search for signatures:
// 0xAA55 - Standard VBIOS signature
// 0x57464F4E ("WFON") - WPR enable
// 0x5746564E ("WFVN") - WPR version

for (offset = 0; offset < size; offset += 0x1000) {
uint32_t sig = *(uint32_t*)(vbios_ptr + offset);

if (sig == 0xAA55) {
// Check for WPR structures
parse_wpr_tables(vbios_ptr + offset);
}
else if (sig == 0x57464F4E || sig == 0x5746564E) {
// WPR enabled in VBIOS
wpr_vbios_enabled = true;
wpr_vbios_offset = offset;
}
}
}</syntaxhighlight>

== Integration with GSP Subsystems ==


=== Memory Allocator (0x429B450) ===

<syntaxhighlight lang="c">// Allocate WPR metadata structures
wpr_region_t *wpr_alloc_region {
return UNK_ram_058A1A9C(0x429B450, sizeof(wpr_region_t));
}

// Allocate bounce buffers for emulation
void *wpr_alloc_bounce(size_t size) {
return UNK_ram_058A1A9C(0x429B450, size);
}</syntaxhighlight>

=== DMA/Copy Engine (0x0588F9C4, 0x05AEC86C) ===

<syntaxhighlight lang="c">// Copy data for WPR emulation
int wpr_emulate_access(wpr_region_t *rgn, void *dst, void *src, size_t size) {
return UNK_ram_0588F9C4(dma_engine, src, dst, size);
}</syntaxhighlight>

=== Logging (0x05AB7DA0) ===

<syntaxhighlight lang="c">// Log WPR events
void wpr_log_event(const char *event_str, uint32_t vf_id, uint64_t addr) {
UNK_ram_05AB7DA0(1, &event_str); // Log string
UNK_ram_05AB7DA0(2, &vf_id); // Log VF ID
UNK_ram_05AB7DA0(3, &addr); // Log address
}</syntaxhighlight>

== vGPU-IO Integration ==


=== Kernel WPR API ===

<syntaxhighlight lang="c">struct gsp_wpr_ops {
int (*protect_write)(struct gsp_device *gsp,
uint32_t vf_id,
uint64_t base, uint64_t size);
int (*protect_read)(struct gsp_device *gsp,
uint32_t vf_id,
uint64_t base, uint64_t size);
int (*unprotect)(struct gsp_device *gsp,
uint32_t vf_id,
uint64_t base);
int (*set_timeout)(struct gsp_device *gsp,
uint32_t vf_id,
uint64_t timeout_ns);
int (*register_callback)(struct gsp_device *gsp,
uint32_t vf_id,
enum wpr_event_type type,
void (*cb)(struct wpr_event *));
};

static const struct gsp_wpr_ops gsp_wpr_ops = {.protect_write = gsp_wpr_write_protect,.protect_read = gsp_wpr_read_protect,.unprotect = gsp_wpr_unprotect,.set_timeout = gsp_wpr_set_timeout,.register_callback = gsp_wpr_register_callback,
};</syntaxhighlight>

=== VF WPR Lifecycle ===

<syntaxhighlight lang="c">// VF initialization: register WPR regions
int gsp_vf_wpr_init(struct gsp_vf *vf) {
// Protect VF's page tables
gsp_wpr_ops.protect_write(vf->gsp, vf->id,
vf->pt_base, vf->pt_size);

// Protect VF's command buffers
gsp_wpr_ops.protect_write(vf->gsp, vf->id,
vf->cmd_base, vf->cmd_size);

// Set default timeout (10ms)
gsp_wpr_ops.set_timeout(vf->gsp, vf->id, 10000000);

// Register completion callbacks
gsp_wpr_ops.register_callback(vf->gsp, vf->id,
WPR_EVENT_WRITE_COMPLETE,
vf_wpr_write_complete_cb);
gsp_wpr_ops.register_callback(vf->gsp, vf->id,
WPR_EVENT_TIMEOUT,
vf_wpr_timeout_cb);

return 0;
}

// VF cleanup
void gsp_vf_wpr_fini(struct gsp_vf *vf) {
gsp_wpr_ops.unprotect(vf->gsp, vf->id, vf->pt_base);
gsp_wpr_ops.unprotect(vf->gsp, vf->id, vf->cmd_base);
//.. unregister callbacks
}</syntaxhighlight>

=== Callback Handling ===

<syntaxhighlight lang="c">static void vf_wpr_write_complete_cb(struct wpr_event *evt) {
struct gsp_vf *vf = evt->vf;

// Log the write attempt
dev_dbg(vf->dev, "WPR write complete: VF=%u addr=0x%llx\n",
vf->id, evt->address);

// If this was a page table update, invalidate TLB
if (evt->address >= vf->pt_base &&
evt->address < vf->pt_base + vf->pt_size) {
gsp_tlb_invalidate(vf->gsp, vf->id);
}
}

static void vf_wpr_timeout_cb(struct wpr_event *evt) {
struct gsp_vf *vf = evt->vf;

dev_warn(vf->dev, "WPR timeout: VF=%u type=%d addr=0x%llx\n",
vf->id, evt->type, evt->address);

// Escalate: reset VF or throttle
if (evt->type == WPR_EVENT_WRITE_TIMEOUT) {
gsp_vf_throttle(vf);
} else {
gsp_vf_reset(vf);
}
}</syntaxhighlight>

== Error Codes ==

{| class="wikitable"
|-
! Code
! Name
! Description
|-
| 0x1E
| ETIME
| Operation timed out
|-
| 0x1F
| EDEV
| Device error
|-
| 0x25
| EOVERFLOW
| Region too large
|-
| 0x37
| EINVAL
| Invalid alignment
|-
| 0x51
| ENOMEM
| Out of memory
|-
| 0x56
| EBUSY
| Region busy
|-
| 0xFFFF
| EPERM
| Permission denied
|}


== Debugging ==


=== Monitor These Addresses ===

<pre>0x04296048: Global error flag
0x0429B750+0x111300: Error status register
0x05E47850-0x05E478F8: WPR string table</pre>

=== GSP Log Patterns ===

<pre>WPR_WRITE_COMPLETE VF=<id> ADDR=<addr>
WPR_READ_COMPLETE VF=<id> ADDR=<addr>
WPR_WRITE_TIMEOUT VF=<id> ADDR=<addr>
WPR_READ_TIMEOUT VF=<id> ADDR=<addr>
NV_WPR_WRITE_COMPLETE VF=<id> ADDR=<addr>
NV_WPR_READ_COMPLETE VF=<id> ADDR=<addr>
NV_WPR_WRITE_TIMEOUT VF=<id> ADDR=<addr>
NV_WPR_READ_TIMEOUT VF=<id> ADDR=<addr></pre>

=== Trace Points ===

<syntaxhighlight lang="c">// In kernel driver
trace_gsp_wpr_protect(vf_id, base, size, type);
trace_gsp_wpr_event(vf_id, event_type, address, status);
trace_gsp_wpr_timeout(vf_id, address, elapsed_ns);</syntaxhighlight>

-----


== Reference ==

* Handler 1: <code>FUN_ram_04f00b0c_ram_04f00b0c.c</code> (62 KB)
* Handler 2: <code>FUN_ram_04f00c78_ram_04f00c78.c</code> (62 KB)
* RPC Types: Handled via primary/secondary dispatchers

WPR Management - Revision history

WikiBot: Fix repository links: point to the cgit tree URLs

WikiBot: Carry the site-wide About/licensing message on every page (2026-10-12)

WikiBot: Re-sync page from tracked wiki source: fix cross-document links and diagram; refresh status

WikiBot: Remove unpaired blockquote tags left by reference cleanup