Skip to content

Commit

Permalink
Merge pull request #836 from milaiwi/clean
Browse files Browse the repository at this point in the history 
Added generated documentation for Unix devices #824
  • Loading branch information
@stgraber
stgraber authored May 6, 2024
2 parents 4ea8028 + a053b52 commit 022a2e3
Show file tree
Hide file tree
Showing 7 changed files with 327 additions and 34 deletions.
98 changes: 98 additions & 0 deletions doc/config_options.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,104 @@ User keys can be used in search.
```

<!-- config group cluster-cluster end -->
<!-- config group devices-unix-char-block start -->
```{config:option} gid devices-unix-char-block
:default: "0"
:shortdesc: "GID of the device owner in the instance"
:type: "int"

```

```{config:option} major devices-unix-char-block
:default: "device on host"
:shortdesc: "Device major number"
:type: "int"

```

```{config:option} minor devices-unix-char-block
:default: "device on host"
:shortdesc: "Device minor number"
:type: "int"

```

```{config:option} mode devices-unix-char-block
:default: "0660"
:shortdesc: "Mode of the device in the instance"
:type: "int"

```

```{config:option} path devices-unix-char-block
:shortdesc: "Path inside the instance (one of `source` and `path` must be set)"
:type: "string"

```

```{config:option} required devices-unix-char-block
:default: "true"
:shortdesc: "Whether this device is required to start the instance"
:type: "bool"

```

```{config:option} source devices-unix-char-block
:shortdesc: "Path on the host (one of `source` and `path` must be set)"
:type: "string"

```

```{config:option} uid devices-unix-char-block
:default: "0"
:shortdesc: "UID of the device owner in the instance"
:type: "int"

```

<!-- config group devices-unix-char-block end -->
<!-- config group devices-unix-hotplug start -->
```{config:option} gid devices-unix-hotplug
:default: "0"
:shortdesc: "GID of the device owner in the instance"
:type: "int"

```

```{config:option} mode devices-unix-hotplug
:default: "0660"
:shortdesc: "Mode of the device in the instance"
:type: "int"

```

```{config:option} productid devices-unix-hotplug
:shortdesc: "The product ID of the USB device"
:type: "string"

```

```{config:option} required devices-unix-hotplug
:default: "true"
:shortdesc: "Whether this device is required to start the instance"
:type: "bool"

```

```{config:option} uid devices-unix-hotplug
:default: "0"
:shortdesc: "UID of the device owner in the instance"
:type: "int"

```

```{config:option} vendorid devices-unix-hotplug
:shortdesc: "The vendor ID of the USB device"
:type: "string"

```

<!-- config group devices-unix-hotplug end -->
<!-- config group devices-usb start -->
```{config:option} busnum devices-usb
:shortdesc: "The bus number of which the USB device is attached"
Expand Down
15 changes: 5 additions & 10 deletions doc/reference/devices_unix_block.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,11 @@ You can read from the device and write to it.

`unix-block` devices have the following device options:

Key | Type | Default | Description
:-- | :-- | :-- | :--
`gid` | int | `0` | GID of the device owner in the instance
`major` | int | device on host | Device major number
`minor` | int | device on host | Device minor number
`mode` | int | `0660` | Mode of the device in the instance
`path` | string | - | Path inside the instance (one of `source` and `path` must be set)
`required` | bool | `true` | Whether this device is required to start the instance (see {ref}`devices-unix-block-hotplugging`)
`source` | string | - | Path on the host (one of `source` and `path` must be set)
`uid` | int | `0` | UID of the device owner in the instance
% Include content from [../config_options.txt](../config_options.txt)
```{include} ../config_options.txt
:start-after: <!-- config group devices-unix-char-block start -->
:end-before: <!-- config group devices-unix-char-block end -->
```

(devices-unix-block-hotplugging)=
## Hotplugging
Expand Down
15 changes: 5 additions & 10 deletions doc/reference/devices_unix_char.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,11 @@ You can read from the device and write to it.

`unix-char` devices have the following device options:

Key | Type | Default | Description
:-- | :-- | :-- | :--
`gid` | int | `0` | GID of the device owner in the instance
`major` | int | device on host | Device major number
`minor` | int | device on host | Device minor number
`mode` | int | `0660` | Mode of the device in the instance
`path` | string | - | Path inside the instance (one of `source` and `path` must be set)
`required` | bool | `true` | Whether this device is required to start the instance (see {ref}`devices-unix-char-hotplugging`)
`source` | string | - | Path on the host (one of `source` and `path` must be set)
`uid` | int | `0` | UID of the device owner in the instance
% Include content from [../config_options.txt](../config_options.txt)
```{include} ../config_options.txt
:start-after: <!-- config group devices-unix-char-block start -->
:end-before: <!-- config group devices-unix-char-block end -->
```

(devices-unix-char-hotplugging)=
## Hotplugging
Expand Down
13 changes: 5 additions & 8 deletions doc/reference/devices_unix_hotplug.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,8 @@ The implementation depends on `systemd-udev` to be run on the host.

`unix-hotplug` devices have the following device options:

Key | Type | Default | Description
:-- | :-- | :-- | :--
`gid` | int | `0` | GID of the device owner in the instance
`mode` | int | `0660` | Mode of the device in the instance
`productid` | string | - | The product ID of the Unix device
`required` | bool | `false` | Whether this device is required to start the instance (the default is `false`, and all devices can be hotplugged)
`uid` | int | `0` | UID of the device owner in the instance
`vendorid` | string | - | The vendor ID of the Unix device
% Include content from [../config_options.txt](../config_options.txt)
```{include} ../config_options.txt
:start-after: <!-- config group devices-unix-hotplug start -->
:end-before: <!-- config group devices-unix-hotplug end -->
```
65 changes: 59 additions & 6 deletions internal/server/device/unix_common.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,11 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error {
}

rules := map[string]func(string) error{
// gendoc:generate(entity=devices, group=unix-char-block, key=source)
//
// ---
// type: string
// shortdesc: Path on the host (one of `source` and `path` must be set)
"source": func(value string) error {
if value == "" {
return nil
Expand All @@ -56,13 +61,61 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error {

return &drivers.ErrInvalidPath{PrefixPath: d.state.DevMonitor.PrefixPath()}
},
"path": validate.IsAny,
"major": unixValidDeviceNum,
"minor": unixValidDeviceNum,
"uid": unixValidUserID,
"gid": unixValidUserID,
"mode": unixValidOctalFileMode,

// gendoc:generate(entity=devices, group=unix-char-block, key=gid)
//
// ---
// type: int
// default: 0
// shortdesc: GID of the device owner in the instance
"gid": unixValidUserID,

// gendoc:generate(entity=devices, group=unix-char-block, key=major)
//
// ---
// type: int
// default: device on host
// shortdesc: Device major number
"major": unixValidDeviceNum,

// gendoc:generate(entity=devices, group=unix-char-block, key=minor)
//
// ---
// type: int
// default: device on host
// shortdesc: Device minor number
"minor": unixValidDeviceNum,

// gendoc:generate(entity=devices, group=unix-char-block, key=mode)
//
// ---
// type: int
// default: 0660
// shortdesc: Mode of the device in the instance
"mode": unixValidOctalFileMode,

// gendoc:generate(entity=devices, group=unix-char-block, key=path)
//
// ---
// type: string
// shortdesc: Path inside the instance (one of `source` and `path` must be set)
"path": validate.IsAny,

// gendoc:generate(entity=devices, group=unix-char-block, key=required)
//
// ---
// type: bool
// default: true
// shortdesc: Whether this device is required to start the instance
"required": validate.Optional(validate.IsBool),

// gendoc:generate(entity=devices, group=unix-char-block, key=uid)
//
// ---
// type: int
// default: 0
// shortdesc: UID of the device owner in the instance
"uid": unixValidUserID,
}

err := d.config.Validate(rules)
Expand Down
39 changes: 39 additions & 0 deletions internal/server/device/unix_hotplug.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,50 @@ func (d *unixHotplug) validateConfig(instConf instance.ConfigReader) error {
}

rules := map[string]func(string) error{
// gendoc:generate(entity=devices, group=unix-hotplug, key=vendorid)
//
// ---
// type: string
// shortdesc: The vendor ID of the USB device
"vendorid": validate.Optional(validate.IsDeviceID),

// gendoc:generate(entity=devices, group=unix-hotplug, key=productid)
//
// ---
// type: string
// shortdesc: The product ID of the USB device
"productid": validate.Optional(validate.IsDeviceID),

// gendoc:generate(entity=devices, group=unix-hotplug, key=uid)
//
// ---
// type: int
// default: 0
// shortdesc: UID of the device owner in the instance
"uid": unixValidUserID,

// gendoc:generate(entity=devices, group=unix-hotplug, key=gid)
//
// ---
// type: int
// default: 0
// shortdesc: GID of the device owner in the instance
"gid": unixValidUserID,

// gendoc:generate(entity=devices, group=unix-hotplug, key=mode)
//
// ---
// type: int
// default: 0660
// shortdesc: Mode of the device in the instance
"mode": unixValidOctalFileMode,

// gendoc:generate(entity=devices, group=unix-hotplug, key=required)
//
// ---
// type: bool
// default: true
// shortdesc: Whether this device is required to start the instance
"required": validate.Optional(validate.IsBool),
}

Expand Down
Loading

0 comments on commit 022a2e3

Please sign in to comment.