Skip to content

Commit

Permalink
Minor userfaultfd fixes
Browse files Browse the repository at this point in the history
- Replace all occurrences of "uffd" with "userfaultfd" in the
documentation.
- Don't hard code userfaultfd as memory tracking mode
  • Loading branch information
panos-lunarg committed Mar 25, 2024
1 parent 2d37240 commit ad0f488
Show file tree
Hide file tree
Showing 3 changed files with 10 additions and 14 deletions.
8 changes: 4 additions & 4 deletions USAGE_android.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,12 +162,12 @@ wise, mechanism. However, as described in
it has some limitation when capturing applications that install their own
signal handler for handling the `SIGSEGV` signal. This limitation exists
only on Linux and Android applications. To work around this
limitation there is the `uffd` mechanism.
limitation there is the `userfaultfd` mechanism.

##### 4. `uffd`
##### 4. `userfaultfd`
This mode utilizes the userfaultfd mechanism provided by the Linux kernel which
allows user space applications to detect and handle page faults.
Under the hood `uffd` is the same mechanism as `page_guard` but instead of trapping
Under the hood `userfaultfd` is the same mechanism as `page_guard` but instead of trapping
the shadow memory regions with the `PROT_NONE` + `SIGSEGV` trick, it
registers those memory regions for tracking to the userfaultfd mechanism.

Expand Down Expand Up @@ -207,7 +207,7 @@ the rest of the threads that potentially are touching pages that are being
reset. The signal used one of the real time signals, the first in the range
[`SIGRTMIN`, `SIGRTMAX`] that has no handler already installed.

`uffd` is less efficient performance wise than `page_guard` but
`userfaultfd` is less efficient performance wise than `page_guard` but
should be fast enough for real-world applications and games.

##### Disabling Debug Breaks Triggered by the GFXReconstruct Layer
Expand Down
12 changes: 6 additions & 6 deletions USAGE_desktop_Vulkan.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,12 +171,12 @@ wise, mechanism. However, as described in
it has some limitation when capturing applications that install their own
signal handler for handling the `SIGSEGV` signal. This limitation exists
only on Linux and Android applications. To work around this
limitation there is the `uffd` mechanism.
limitation there is the `userfaultfd` mechanism.

##### 4. `uffd`
##### 4. `userfaultfd`
This mode utilizes the userfaultfd mechanism provided by the Linux kernel which
allows user space applications to detect and handle page faults.
Under the hood `uffd` is the same mechanism as `page_guard` but instead of trapping
Under the hood `userfaultfd` is the same mechanism as `page_guard` but instead of trapping
the shadow memory regions with the `PROT_NONE` + `SIGSEGV` trick, it
registers those memory regions for tracking to the userfaultfd mechanism.

Expand Down Expand Up @@ -216,7 +216,7 @@ the rest of the threads that potentially are touching pages that are being
reset. The signal used one of the real time signals, the first in the range
[`SIGRTMIN`, `SIGRTMAX`] that has no handler already installed.

`uffd` is less efficient performance wise than `page_guard` but
`userfaultfd` is less efficient performance wise than `page_guard` but
should be fast enough for real-world applications and games.

### Capture Options
Expand Down Expand Up @@ -275,7 +275,7 @@ Log File Create New | GFXRECON_LOG_FILE_CREATE_NEW | BOOL | Specifies that log f
Log File Flush After Write | GFXRECON_LOG_FILE_FLUSH_AFTER_WRITE | BOOL | Flush the log file to disk after each write when true. Default is: `false`
Log File Keep Open | GFXRECON_LOG_FILE_KEEP_OPEN | BOOL | Keep the log file open between log messages when true, or close and reopen the log file for each message when false. Default is: `true`
Log Output to Debug Console | GFXRECON_LOG_OUTPUT_TO_OS_DEBUG_STRING | BOOL | Windows only option. Log messages will be written to the Debug Console with `OutputDebugStringA`. Default is: `false`
Memory Tracking Mode | GFXRECON_MEMORY_TRACKING_MODE | STRING | Specifies the memory tracking mode to use for detecting modifications to mapped Vulkan memory objects. Available options are: `page_guard`, `uffd`, `assisted`, and `unassisted`. See [Understanding GFXReconstruct Layer Memory Capture](#understanding-gfxreconstruct-layer-memory-capture) for more details. Default is `page_guard`.
Memory Tracking Mode | GFXRECON_MEMORY_TRACKING_MODE | STRING | Specifies the memory tracking mode to use for detecting modifications to mapped Vulkan memory objects. Available options are: `page_guard`, `userfaultfd`, `assisted`, and `unassisted`. See [Understanding GFXReconstruct Layer Memory Capture](#understanding-gfxreconstruct-layer-memory-capture) for more details. Default is `page_guard`.
Page Guard Copy on Map | GFXRECON_PAGE_GUARD_COPY_ON_MAP | BOOL | When the `page_guard` memory tracking mode is enabled, copies the content of the mapped memory to the shadow memory immediately after the memory is mapped. Default is: `true`
Page Guard Separate Read Tracking | GFXRECON_PAGE_GUARD_SEPARATE_READ | BOOL | When the `page_guard` memory tracking mode is enabled, copies the content of pages accessed for read from mapped memory to shadow memory on each read. Can overwrite unprocessed shadow memory content when an application is reading from and writing to the same page. Default is: `true`
Page Guard External Memory | GFXRECON_PAGE_GUARD_EXTERNAL_MEMORY | BOOL | When the `page_guard` memory tracking mode is enabled, use the VK_EXT_external_memory_host extension to eliminate the need for shadow memory allocations. For each memory allocation from a host visible memory type, the capture layer will create an allocation from system memory, which it can monitor for write access, and provide that allocation to vkAllocateMemory as external memory. Only available on Windows. Default is `false`
Expand Down Expand Up @@ -320,7 +320,7 @@ After the crash detection library sets its signal handler, it immediately
receives a SIGSEGV event generated by the concurrent write to mapped memory,
which it detects as a crash and terminates the application.

`uffd` mechanism was introduced in order to work around such conflicts.
`userfaultfd` mechanism was introduced in order to work around such conflicts.

#### Memory Tracking Limitations

Expand Down
4 changes: 0 additions & 4 deletions framework/encode/capture_settings.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -485,12 +485,8 @@ void CaptureSettings::ProcessOptions(OptionsMap* options, CaptureSettings* setti
ParseBoolString(FindOption(options, kOptionKeyCaptureFileForceFlush), settings->trace_settings_.force_flush);

// Memory tracking options
#if defined(WIN32) || defined(__APPLE__)
settings->trace_settings_.memory_tracking_mode = ParseMemoryTrackingModeString(
FindOption(options, kOptionKeyMemoryTrackingMode), settings->trace_settings_.memory_tracking_mode);
#else
settings->trace_settings_.memory_tracking_mode = MemoryTrackingMode::kUserfaultfd;
#endif

// Trimming options:
// Trim frame ranges, trim queue submit ranges, and trim frame hotkey are mutually exclusive.
Expand Down

0 comments on commit ad0f488

Please sign in to comment.