From 3524feba7742e4a6b8ef5bc7956e83a6196de692 Mon Sep 17 00:00:00 2001 From: Jerry Jones <28451941+stratusjerry@users.noreply.github.com> Date: Thu, 31 Jul 2025 11:19:42 -0400 Subject: [PATCH] grammar docfixes (#13314) --- doc/docs/debugging.md | 2 +- doc/docs/dev-loop.md | 2 +- doc/docs/technical-documentation/boot-process.md | 2 +- doc/docs/technical-documentation/drvfs.md | 4 ++-- doc/docs/technical-documentation/gns.md | 2 +- doc/docs/technical-documentation/interop.md | 2 +- doc/docs/technical-documentation/localhost.md | 2 +- doc/docs/technical-documentation/mini_init.md | 2 +- doc/docs/technical-documentation/plan9.md | 2 +- doc/docs/technical-documentation/relay.md | 2 +- doc/docs/technical-documentation/session-leader.md | 2 +- doc/docs/technical-documentation/systemd.md | 4 ++-- doc/docs/technical-documentation/wsl.exe.md | 2 +- doc/docs/technical-documentation/wslservice.exe.md | 4 ++-- 14 files changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/docs/debugging.md b/doc/docs/debugging.md index 2780108..8ea8eec 100644 --- a/doc/docs/debugging.md +++ b/doc/docs/debugging.md @@ -24,7 +24,7 @@ Notable ETL providers: - `Error`: Unexpected errors - `CreateVmBegin`, `CreateVmEnd`: Virtual machine lifetime - `CreateNetworkBegin`, `CreateNetworkEnd`: Networking configuration - - `SentMessage`, `ReceivedMessaged`: Communication on the hvsocket channels with Linux. + - `SentMessage`, `ReceivedMessage`: Communication on the hvsocket channels with Linux. - `Microsoft.Windows.Subsystem.Lxss`: Other WSL executables (wsl.exe, wslg.exe, wslconfig.exe, wslrelay.exe, ...) Important events: diff --git a/doc/docs/dev-loop.md b/doc/docs/dev-loop.md index 8aab2e2..e28a294 100644 --- a/doc/docs/dev-loop.md +++ b/doc/docs/dev-loop.md @@ -70,5 +70,5 @@ bin\x64\debug\test.bat /name:*UnitTest* -f See [debugging](debugging.md) for general debugging instructions. -To attach a debugging to the unit test process, use: `/waitfordebugger` when calling `test.bat`. +To attach a debugger to the unit test process, use: `/waitfordebugger` when calling `test.bat`. Use `/breakonfailure` to automatically break on the first test failure. diff --git a/doc/docs/technical-documentation/boot-process.md b/doc/docs/technical-documentation/boot-process.md index 82b7d2a..7edfa00 100644 --- a/doc/docs/technical-documentation/boot-process.md +++ b/doc/docs/technical-documentation/boot-process.md @@ -4,7 +4,7 @@ This page describes the steps in the WSL2 process, from the user invoking [wsl.e ## Overview -The below diagram shows the sequence of event to start bash within a WSL2 distribution. See [WSL architecture](index.md) for details about what each process does. +The below diagram shows the sequence of events to start bash within a WSL2 distribution. See [WSL architecture](index.md) for details about what each process does. ```mermaid sequenceDiagram diff --git a/doc/docs/technical-documentation/drvfs.md b/doc/docs/technical-documentation/drvfs.md index 3912b52..857c7b5 100644 --- a/doc/docs/technical-documentation/drvfs.md +++ b/doc/docs/technical-documentation/drvfs.md @@ -16,7 +16,7 @@ When a Linux process is created, [wslservice.exe](wslservice.exe.md) determines When a [session leader](session-leader.md) is created, [wslservice.exe](wslservice.exe.md) starts a [plan9](https://9fans.github.io/plan9port/man/man9/intro.html) file server. This file server can be connected to from the WSL2 virtual machine to mount Windows drives. -When the WSL distribution is created, [wslservice.exe](wslservice.exe.md) uses the `LX_INIT_CONFIGURATION_INFORMATION` message to indicate whether the process that created the distribution is elevated or not. Based on this, [init](init.md) will mount either or the elevated, or un-elevated version of the plan9 server. +When the WSL distribution is created, [wslservice.exe](wslservice.exe.md) uses the `LX_INIT_CONFIGURATION_INFORMATION` message to indicate whether the process that created the distribution is elevated or not. Based on this, [init](init.md) will mount either the elevated, or un-elevated version of the plan9 server. Later when the first command is created in the namespace that hasn't been mounted yet, (either elevated, or non-elevated), [wslservice.exe](wslservice.exe.md) sends a `LxInitMessageRemountDrvfs` to [init](init.md), which tell `init` to mount the other namespace. @@ -30,6 +30,6 @@ As long as the Windows plan9 server is running, drives can be mounted simply by mount -t drvfs C: /tmp/my-mount-point ``` -Internally, this handled by `/usr/sbin/mount.drvfs`, which is a symlink to `/init`. When `/init` starts, it looks at `argv[0]` to determine which entrypoint to run. If `argv[0]` is `mount.drvfs`, then `/init` runs the `mount.drvfs` entrypoint (see `MountDrvfsEntry()` in `src/linux/init/drvfs.cpp`). +Internally, this is handled by `/usr/sbin/mount.drvfs`, which is a symlink to `/init`. When `/init` starts, it looks at `argv[0]` to determine which entrypoint to run. If `argv[0]` is `mount.drvfs`, then `/init` runs the `mount.drvfs` entrypoint (see `MountDrvfsEntry()` in `src/linux/init/drvfs.cpp`). Depending on the distribution configuration, `mount.drvfs` will either mount the drive as `drvfs` (WSL1), or `plan9`, `virtio-plan9` or `virtiofs` (WSL), depending on [.wslconfig](https://learn.microsoft.com/windows/wsl/wsl-config). \ No newline at end of file diff --git a/doc/docs/technical-documentation/gns.md b/doc/docs/technical-documentation/gns.md index b82c324..f309932 100644 --- a/doc/docs/technical-documentation/gns.md +++ b/doc/docs/technical-documentation/gns.md @@ -1,6 +1,6 @@ # GNS -`gns` is a process created by `mini_init`. Its jobs is to configure networking within the WSL2 virtual machine. +`gns` is a process created by `mini_init`. Its job is to configure networking within the WSL2 virtual machine. ## Networking configuration diff --git a/doc/docs/technical-documentation/interop.md b/doc/docs/technical-documentation/interop.md index 0e9c41a..ed029ba 100644 --- a/doc/docs/technical-documentation/interop.md +++ b/doc/docs/technical-documentation/interop.md @@ -25,6 +25,6 @@ Inside Linux, each [session leader](session-leader.md), and each instance of [in `/init` uses the `$WSL_INTEROP` environment variable to know which server to connect to. If the variable is not set, `/init` will try to connect to `/run/WSL/${pid}_interop`, with its own PID. If that doesn't work, `/init` will try its parent's pid, and then will continue to go up the chain until it reached [init](init.md). -Once connected `/init` sends a `LxInitMessageCreateProcess` (WSL1) or a `LxInitMessageCreateProcessUtilityVm` (WSL2), which then forwards that message to the associated Windows process, which will launched the requested command and relay its output to `/init`. +Once connected `/init` sends a `LxInitMessageCreateProcess` (WSL1) or a `LxInitMessageCreateProcessUtilityVm` (WSL2), which then forwards that message to the associated Windows process, which will launch the requested command and relay its output to `/init`. See `src/linux/init/binfmt.cpp` \ No newline at end of file diff --git a/doc/docs/technical-documentation/localhost.md b/doc/docs/technical-documentation/localhost.md index 8755d91..8aa6105 100644 --- a/doc/docs/technical-documentation/localhost.md +++ b/doc/docs/technical-documentation/localhost.md @@ -9,6 +9,6 @@ When `wsl2.networkingMode` is set to NAT, `localhost` will watch for bound TCP p ## Mirrored networking -In mirrored mode, `localhost` register a BPF program to intercept calls to `bind()`, and forward the calls to Windows via [wslservice.exe](wslservice.exe.md) so Windows can route the network traffic directly to the WSL2 virtual machine. +In mirrored mode, `localhost` registers a BPF program to intercept calls to `bind()`, and forward the calls to Windows via [wslservice.exe](wslservice.exe.md) so Windows can route the network traffic directly to the WSL2 virtual machine. See `src/linux/localhost.cpp`. \ No newline at end of file diff --git a/doc/docs/technical-documentation/mini_init.md b/doc/docs/technical-documentation/mini_init.md index 06be8f3..d3b6820 100644 --- a/doc/docs/technical-documentation/mini_init.md +++ b/doc/docs/technical-documentation/mini_init.md @@ -22,7 +22,7 @@ The other hvsocket channel is used to send notifications to [wslservice.exe](wsl ## Networking configuration -As part of the boot process, `mini_init` also launches the [gns binary](gns.md) which managed networking configuration +As part of the boot process, `mini_init` also launches the [gns binary](gns.md) which manages networking configuration ## Other tasks diff --git a/doc/docs/technical-documentation/plan9.md b/doc/docs/technical-documentation/plan9.md index 7dd2592..fd311f2 100644 --- a/doc/docs/technical-documentation/plan9.md +++ b/doc/docs/technical-documentation/plan9.md @@ -12,7 +12,7 @@ In WSL2 distributions, `plan9` runs its filesystem through an `hvsocket` ## Accessing the distribution files from Windows -From Windows, a special redirector driver (p9rdr.sys) registers both `\\wsl$` and `\\wsl.localhost`. When either of those paths are accessed, `p9rdr.sys` calls [wslservice.exe](wslservice.exe.md) to list the available distributions for a given Windows users. +From Windows, a special redirector driver (p9rdr.sys) registers both `\\wsl$` and `\\wsl.localhost`. When either of those paths are accessed, `p9rdr.sys` calls [wslservice.exe](wslservice.exe.md) to list the available distributions for a given Windows user. When a distribution path is accessed (like `\\wsl.localhost\debian`), `p9rdr.sys` calls into [wslservice.exe](wslservice.exe.md) via COM to start the distribution, and connect to its plan9 server, which allows the files to be accessed from Windows. diff --git a/doc/docs/technical-documentation/relay.md b/doc/docs/technical-documentation/relay.md index 239539b..29db625 100644 --- a/doc/docs/technical-documentation/relay.md +++ b/doc/docs/technical-documentation/relay.md @@ -1,6 +1,6 @@ # Relay -Relay is a WSL2 linux process creating by a [session leader](session-leader.md). Its job is to create a linux process on behalf of the user, and relay its output back to Windows. +Relay is a WSL2 linux process created by a [session leader](session-leader.md). Its job is to create a linux process on behalf of the user, and relay its output back to Windows. ## Creating a user process diff --git a/doc/docs/technical-documentation/session-leader.md b/doc/docs/technical-documentation/session-leader.md index 63b6caf..851e2aa 100644 --- a/doc/docs/technical-documentation/session-leader.md +++ b/doc/docs/technical-documentation/session-leader.md @@ -23,4 +23,4 @@ When running in a WSL1 distribution, the session leader forks(), and uses the ch ## Creating a WSL2 process -When running in a WSL2 distribution, the session leaders forks() to create a [relay](relay.md) process, which is responsible for creating the user process and relaying its output back to [wsl.exe](wsl.exe.md) \ No newline at end of file +When running in a WSL2 distribution, the session leader forks() to create a [relay](relay.md) process, which is responsible for creating the user process and relaying its output back to [wsl.exe](wsl.exe.md) \ No newline at end of file diff --git a/doc/docs/technical-documentation/systemd.md b/doc/docs/technical-documentation/systemd.md index 2f33aef..9648711 100644 --- a/doc/docs/technical-documentation/systemd.md +++ b/doc/docs/technical-documentation/systemd.md @@ -7,7 +7,7 @@ Systemd support for a WSL distribution can be enabled by setting the following i systemd=true ``` -When enabled, [init](init.md) will take launch `/sbin/init` (which points to systemd's init) when the distribution starts. One key difference when this setting is enabled is that [init](init.md) won't be pid 1 in the given distribution, since systemd's init requires running as pid 1, so [init](init.md) will fork(), and launch systemd in the parent while continuing WSL configuration in the child process. +When enabled, [init](init.md) will launch `/sbin/init` (which points to systemd's init) when the distribution starts. One key difference when this setting is enabled is that [init](init.md) won't be pid 1 in the given distribution, since systemd's init requires running as pid 1, so [init](init.md) will fork(), and launch systemd in the parent while continuing WSL configuration in the child process. After launching `/sbin/init`, [init](init.md) waits for systemd to be ready by waiting for `systemctl is-system-running` to return either `running`, or `degraded`. After a given amount of time, WSL will time out and allow the distribution to continue starting, even if systemd isn't ready. @@ -19,5 +19,5 @@ When systemd is enabled, WSL tries synchronizes launching processes with systemd To improve compatibility with systemd, WSL creates various systemd configuration files during boot (under `/run`). These configurations files are used to: -- Protect the WSL [binfmt interpret](interop.md) from being deleted by `systemd-binfmt.service` +- Protect the WSL [binfmt interpreter](interop.md) from being deleted by `systemd-binfmt.service` - Protect the X11 socket from being deleted by `systemd-tmpfiles-setup.service` diff --git a/doc/docs/technical-documentation/wsl.exe.md b/doc/docs/technical-documentation/wsl.exe.md index 38a8432..98aff6a 100644 --- a/doc/docs/technical-documentation/wsl.exe.md +++ b/doc/docs/technical-documentation/wsl.exe.md @@ -1,6 +1,6 @@ # wsl.exe -wsl.exe is main command line entrypoint from WSL. Its job is to: +wsl.exe is the main command line entrypoint for WSL. Its job is to: - Parse the command line arguments (See `src/windows/common/wslclient.cpp`) - Call [wslservice.exe](wslservice.exe.md) via COM to launch WSL (see `src/windows/common/svccomm.cpp`) diff --git a/doc/docs/technical-documentation/wslservice.exe.md b/doc/docs/technical-documentation/wslservice.exe.md index 9e2b683..8b6de5d 100644 --- a/doc/docs/technical-documentation/wslservice.exe.md +++ b/doc/docs/technical-documentation/wslservice.exe.md @@ -4,7 +4,7 @@ WslService is a session 0 service, running as SYSTEM. Its job is to manage WSL s ## COM Interface -Clients can connect to WslService via its COM interface, ILxssUserSession. Its definition can be found in `src/windows/service/incwslservice.idl`. +Clients can connect to WslService via its COM interface, ILxssUserSession. Its definition can be found in `src/windows/service/inc/wslservice.idl`. When a COM client calls [CoCreateInstance()](https://learn.microsoft.com/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance) on this interface, the service receives the requests via `LxssUserSessionFactory` (see `src/windows/service/LxssUserSessionFactory.cpp`) and returns an instance of `LxssUserSession` (see `src/windows/service/LxssUserSession.cpp`) per Windows user (calling CoCreateInstance() multiple times from the same Windows user accounts returns the same instance). @@ -19,7 +19,7 @@ The client can then use its `ILxssUserSession` instance to call methods into the WslService manages the WSL2 Virtual Machine. The virtual machine management logic can be found in `src/windows/service/WslCoreVm.cpp`. -Once booted, WslService maintains an [hvsocket](https://learn.microsoft.com/virtualization/hyper-v-on-windows/user-guide/make-integration-service) with the Virtual Machine which it uses to send various commands to Linux processes (see [mini_init](mini_init.md) for more details. +Once booted, WslService maintains an [hvsocket](https://learn.microsoft.com/virtualization/hyper-v-on-windows/user-guide/make-integration-service) with the Virtual Machine which it uses to send various commands to Linux processes (see [mini_init](mini_init.md) for more details). ## WSL2 Distributions