Add docs for --device option in Windows #1663

cwilhit · 2019-02-07T18:00:42Z

Signed-off-by: Craig Wilhite [email protected]

Adds documentation portion for #1606. Includes a reference for how to run with --device on Windows & explain limitations of the feature (no Hyper-V isolation, no LCOW).

@jhowardmsft FYI

lowenna · 2019-02-07T18:03:31Z

docs/reference/commandline/run.md

 > that may be removed should not be added to untrusted containers with
 > `--device`.

+For Windows, the format of the string passed to the `--device` option is in the form of `--device=<IdType>/<Id>`. Today, Windows only supports an IdType of `class` and the Id as a [device interface class GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). For a list of container-supported device interface class GUIDs, please refer to the table defined in the [Windows container docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers).


Rather than Today, perhaps state what versions of Windows. (AFAIK, this is RS5/1809 on only).

codecov-io · 2019-02-07T18:08:59Z

Codecov Report

Merging #1663 into master will increase coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #1663      +/-   ##
==========================================
+ Coverage   56.12%   56.13%   +<.01%     
==========================================
  Files         306      306              
  Lines       20964    20931      -33     
==========================================
- Hits        11766    11749      -17     
+ Misses       8345     8334      -11     
+ Partials      853      848       -5

lowenna

LGTM (not a maintainer in this repo)

thaJeztah

Thanks! I left some suggestions below (feel free to amend your commits to use those). Could you also squash your commits, so that there's only a single commit in this pull request? Let me know if you need help doing so 👍

thaJeztah · 2019-02-08T14:42:54Z

docs/reference/commandline/run.md

 > that may be removed should not be added to untrusted containers with
 > `--device`.

+For Windows, the format of the string passed to the `--device` option is in the form of `--device=<IdType>/<Id>`. Beginning with Windows Server 2019 and Windows 10 October 2018 Update, Windows only supports an IdType of `class` and the Id as a [device interface class GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). For a list of container-supported device interface class GUIDs, please refer to the table defined in the [Windows container docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers).


Trying to avoid "please" in the documentation; perhaps

Refer to the table defined in the [Windows container documentation](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers) for a list of container-supported device interface class GUIDs.

Also, could you wrap these to ~80 chars?

Suggested change

For Windows, the format of the string passed to the `--device` option is in the form of `--device=<IdType>/<Id>`. Beginning with Windows Server 2019 and Windows 10 October 2018 Update, Windows only supports an IdType of `class` and the Id as a [device interface class GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). For a list of container-supported device interface class GUIDs, please refer to the table defined in the [Windows container docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers).

For Windows, the format of the string passed to the `--device` option is in

the form of `--device=<IdType>/<Id>`. Beginning with Windows Server 2019

and Windows 10 October 2018 Update, Windows only supports an IdType of

`class` and the Id as a [device interface class

GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes).

Refer to the table defined in the [Windows container

documentation](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers)

for a list of container-supported device interface class GUIDs.

Thanks, added these fixes.

thaJeztah · 2019-02-08T14:46:45Z

docs/reference/commandline/run.md


+For Windows, the format of the string passed to the `--device` option is in the form of `--device=<IdType>/<Id>`. Beginning with Windows Server 2019 and Windows 10 October 2018 Update, Windows only supports an IdType of `class` and the Id as a [device interface class GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). For a list of container-supported device interface class GUIDs, please refer to the table defined in the [Windows container docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers).
+
+When this option is specified for a process-isolated Windows container, _all_ devices which implement the requested device interface class GUID will be made available in the container. For example, the command below will make all COM ports on the host visibile in the container.


Should it be "devices that implement" (instead of "which"?)

Also, try to avoid future tense in technical documentation; here's a quick go at changing it to remove the future tense, and wrap the paragraph to 80 chars;

Suggested change

When this option is specified for a process-isolated Windows container, _all_ devices which implement the requested device interface class GUID will be made available in the container. For example, the command below will make all COM ports on the host visibile in the container.

If this option is specified for a process-isolated Windows container, _all_

devices that implement the requested device interface class GUID are made

available in the container. For example, the command below makes all COM

ports on the host visible in the container.

You are correct--I've now learned when to use 'which' vs 'that'. It always confounded me in the past.

thaJeztah · 2019-02-08T14:50:15Z

docs/reference/commandline/run.md

+PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.microsoft.com/windows/servercore:ltsc2019 
+```
+
+> **Note**: `--device` may only be used on Windows with process-isolated Windows containers. This option will fail if the container


Slightly changed to wrap to 80-chars, and remove future tense;

Suggested change

> **Note**: `--device` may only be used on Windows with process-isolated Windows containers. This option will fail if the container

> **Note**: the `--device` option is only supported on process-isolated

> Windows containers. This option fails if the container isolation is `hyperv`

> or when running Linux Containers on Windows (LCOW).

cwilhit · 2019-02-13T16:38:45Z

@thaJeztah Ok, incorporated the changes. This is the first time I've squashed commits before, but I believe I got it correctly. Per instructions online, I had to force push to my branch on Github.

silvin-lubecki

LGTM, thank you for this contribution @cwilhit 👍

thaJeztah

spotted two markdown issues, but LGTM otherwise, so ok to merge after those are addressed (thanks!)

thaJeztah · 2019-02-15T15:12:11Z

docs/reference/commandline/run.md

+the form of `--device=<IdType>/<Id>`. Beginning with Windows Server 2019
+and Windows 10 October 2018 Update, Windows only supports an IdType of
+`class` and the Id as a [device interface class
+GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-


oh; the URL itself cannot be wrapped (it's ok for the caption, but not for the URL)

thaJeztah · 2019-02-15T15:12:31Z

docs/reference/commandline/run.md

+GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-
+interface-classes).
+Refer to the table defined in the [Windows container
+docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy


…mitations (no Hyper-V isolation, no LCOW). Signed-off-by: Craig Wilhite <[email protected]>

thaJeztah

LGTM, thanks!

cwilhit requested a review from thaJeztah as a code owner February 7, 2019 18:00

GordonTheTurtle added the status/0-triage label Feb 7, 2019

lowenna reviewed Feb 7, 2019

View reviewed changes

lowenna approved these changes Feb 7, 2019

View reviewed changes

thaJeztah requested changes Feb 8, 2019

View reviewed changes

thaJeztah added kind/docs status/3-docs-review platform/windows and removed status/0-triage labels Feb 8, 2019

silvin-lubecki approved these changes Feb 13, 2019

View reviewed changes

thaJeztah requested changes Feb 15, 2019

View reviewed changes

Include reference for how to run with --device on Windows. Explain li…

90c595f

…mitations (no Hyper-V isolation, no LCOW). Signed-off-by: Craig Wilhite <[email protected]>

thaJeztah approved these changes Mar 19, 2019

View reviewed changes

thaJeztah merged commit e4aa87f into docker:master Mar 19, 2019

GordonTheTurtle added this to the 19.03.0 milestone Mar 19, 2019


		For Windows, the format of the string passed to the `--device` option is in the form of `--device=<IdType>/<Id>`. Beginning with Windows Server 2019 and Windows 10 October 2018 Update, Windows only supports an IdType of `class` and the Id as a [device interface class GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). For a list of container-supported device interface class GUIDs, please refer to the table defined in the [Windows container docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers).

		When this option is specified for a process-isolated Windows container, _all_ devices which implement the requested device interface class GUID will be made available in the container. For example, the command below will make all COM ports on the host visibile in the container.

-When this option is specified for a process-isolated Windows container, _all_ devices which implement the requested device interface class GUID will be made available in the container. For example, the command below will make all COM ports on the host visibile in the container.
+If this option is specified for a process-isolated Windows container, _all_
+devices that implement the requested device interface class GUID are made
+available in the container. For example, the command below makes all COM
+ports on the host visible in the container.

-> **Note**: `--device` may only be used on Windows with process-isolated Windows containers. This option will fail if the container
+> **Note**: the `--device` option is only supported on process-isolated
+> Windows containers. This option fails if the container isolation is `hyperv`
+> or when running Linux Containers on Windows (LCOW).

Add docs for --device option in Windows #1663

Add docs for --device option in Windows #1663

Uh oh!

Conversation

cwilhit commented Feb 7, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov-io commented Feb 7, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

lowenna left a comment

Choose a reason for hiding this comment

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cwilhit commented Feb 13, 2019

Uh oh!

silvin-lubecki left a comment

Choose a reason for hiding this comment

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov-io commented Feb 7, 2019 •

edited

Loading