3524feba · samitouri/QOSAMI-WSL-2 · siGit Code & Deploy

doc/docs/debugging.md

+1 -1

@@ -24,7 +24,7 @@ Notable ETL providers:

24 - `Error`: Unexpected errors

25 - `CreateVmBegin`, `CreateVmEnd`: Virtual machine lifetime

26 - `CreateNetworkBegin`, `CreateNetworkEnd`: Networking configuration

27 - - `SentMessage`, `ReceivedMessaged`: Communication on the hvsocket channels with Linux.

27 + - `SentMessage`, `ReceivedMessage`: Communication on the hvsocket channels with Linux.

28

29 - `Microsoft.Windows.Subsystem.Lxss`: Other WSL executables (wsl.exe, wslg.exe, wslconfig.exe, wslrelay.exe, ...)

30 Important events:

doc/docs/dev-loop.md

+1 -1

@@ -70,5 +70,5 @@ bin\x64\debug\test.bat /name:*UnitTest* -f

70

71 See [debugging](debugging.md) for general debugging instructions.

72

73 -To attach a debugging to the unit test process, use: `/waitfordebugger` when calling `test.bat`.

73 +To attach a debugger to the unit test process, use: `/waitfordebugger` when calling `test.bat`.

74 Use `/breakonfailure` to automatically break on the first test failure.

doc/docs/technical-documentation/boot-process.md

+1 -1

@@ -4,7 +4,7 @@ This page describes the steps in the WSL2 process, from the user invoking [wsl.e

4

5 ## Overview

6

7 -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.

7 +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.

8

9 ```mermaid

10 sequenceDiagram

doc/docs/technical-documentation/drvfs.md

+2 -2

@@ -16,7 +16,7 @@ When a Linux process is created, [wslservice.exe](wslservice.exe.md) determines

16

17 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.

18

19 -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.

19 +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.

20

21 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.

22

@@ -30,6 +30,6 @@ As long as the Windows plan9 server is running, drives can be mounted simply by

30 mount -t drvfs C: /tmp/my-mount-point

31 ```

32

33 -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`).

33 +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`).

34

35 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

doc/docs/technical-documentation/gns.md

+1 -1

@@ -1,6 +1,6 @@

1 # GNS

2

3 -`gns` is a process created by `mini_init`. Its jobs is to configure networking within the WSL2 virtual machine.

3 +`gns` is a process created by `mini_init`. Its job is to configure networking within the WSL2 virtual machine.

4

5 ## Networking configuration

6

doc/docs/technical-documentation/interop.md

+1 -1

@@ -25,6 +25,6 @@ Inside Linux, each [session leader](session-leader.md), and each instance of [in

25

26 `/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).

27

28 -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`.

28 +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`.

29

30 See `src/linux/init/binfmt.cpp`

\ No newline at end of file

doc/docs/technical-documentation/localhost.md

+1 -1

@@ -9,6 +9,6 @@ When `wsl2.networkingMode` is set to NAT, `localhost` will watch for bound TCP p

9

10 ## Mirrored networking

11

12 -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.

12 +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.

13

14 See `src/linux/localhost.cpp`.

\ No newline at end of file

doc/docs/technical-documentation/mini_init.md

+1 -1

@@ -22,7 +22,7 @@ The other hvsocket channel is used to send notifications to [wslservice.exe](wsl

22

23 ## Networking configuration

24

25 -As part of the boot process, `mini_init` also launches the [gns binary](gns.md) which managed networking configuration

25 +As part of the boot process, `mini_init` also launches the [gns binary](gns.md) which manages networking configuration

26

27 ## Other tasks

28

doc/docs/technical-documentation/plan9.md

+1 -1

@@ -12,7 +12,7 @@ In WSL2 distributions, `plan9` runs its filesystem through an `hvsocket`

12

13 ## Accessing the distribution files from Windows

14

15 -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.

15 +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.

16

17 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.

18

doc/docs/technical-documentation/relay.md

+1 -1

@@ -1,6 +1,6 @@

1 # Relay

2

3 -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.

3 +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.

4

5 ## Creating a user process

6

doc/docs/technical-documentation/session-leader.md

+1 -1

@@ -23,4 +23,4 @@ When running in a WSL1 distribution, the session leader forks(), and uses the ch

23

24 ## Creating a WSL2 process

25

26 -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

26 +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

doc/docs/technical-documentation/systemd.md

+2 -2

@@ -7,7 +7,7 @@ Systemd support for a WSL distribution can be enabled by setting the following i

7 systemd=true

8 ```

9

10 -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.

10 +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.

11

12 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.

13

@@ -19,5 +19,5 @@ When systemd is enabled, WSL tries synchronizes launching processes with systemd

19

20 To improve compatibility with systemd, WSL creates various systemd configuration files during boot (under `/run`). These configurations files are used to:

21

22 -- Protect the WSL [binfmt interpret](interop.md) from being deleted by `systemd-binfmt.service`

22 +- Protect the WSL [binfmt interpreter](interop.md) from being deleted by `systemd-binfmt.service`

23 - Protect the X11 socket from being deleted by `systemd-tmpfiles-setup.service`

doc/docs/technical-documentation/wsl.exe.md

+1 -1

@@ -1,6 +1,6 @@

1 # wsl.exe

2

3 -wsl.exe is main command line entrypoint from WSL. Its job is to:

3 +wsl.exe is the main command line entrypoint for WSL. Its job is to:

4

5 - Parse the command line arguments (See `src/windows/common/wslclient.cpp`)

6 - Call [wslservice.exe](wslservice.exe.md) via COM to launch WSL (see `src/windows/common/svccomm.cpp`)

doc/docs/technical-documentation/wslservice.exe.md

+2 -2

@@ -4,7 +4,7 @@ WslService is a session 0 service, running as SYSTEM. Its job is to manage WSL s

4

5 ## COM Interface

6

7 -Clients can connect to WslService via its COM interface, ILxssUserSession. Its definition can be found in `src/windows/service/incwslservice.idl`.

7 +Clients can connect to WslService via its COM interface, ILxssUserSession. Its definition can be found in `src/windows/service/inc/wslservice.idl`.

8

9 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).

10

@@ -19,7 +19,7 @@ The client can then use its `ILxssUserSession` instance to call methods into the

19

20 WslService manages the WSL2 Virtual Machine. The virtual machine management logic can be found in `src/windows/service/WslCoreVm.cpp`.

21

22 -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.

22 +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).

23

24 ## WSL2 Distributions

25

grammar docfixes (#13314)