Page MenuHomeFreeBSD
Differential D16452

top(1): forgot in r336160
ClosedPublic
Actions

Authored by daichi on Jul 26 2018, 10:51 AM.
Tags
None
Referenced Files
Unknown Object (File)
Mon, Mar 24, 5:24 AM
Unknown Object (File)
Feb 21 2025, 11:52 PM
Unknown Object (File)
Feb 8 2025, 4:29 PM
Unknown Object (File)
Jan 17 2025, 11:44 PM
Unknown Object (File)
Jan 14 2025, 6:23 PM
Unknown Object (File)
Dec 11 2024, 6:08 AM
Unknown Object (File)
Nov 22 2024, 4:45 PM
Unknown Object (File)
Nov 22 2024, 4:45 PM
View All 38 Files
Subscribers
imp

Details

Reviewers
eadler
gnn
Group Reviewers
Restricted Owners Package(Owns No Changed Paths)
Commits
rS336737: top(1): forgot in r336160
Summary

top(1): forgot in r336160

See:
https://reviews.freebsd.org/D16203

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

daichi created this revision.Jul 26 2018, 10:51 AM
daichi edited the summary of this revision. (Show Details)Jul 26 2018, 11:37 AM

Added the rollback's URL

gnn accepted this revision.Jul 26 2018, 12:41 PM
This revision is now accepted and ready to land.Jul 26 2018, 12:41 PM
Closed by commit rS336737: top(1): forgot in r336160 (authored by daichi). · Explain WhyJul 26 2018, 1:53 PM
This revision was automatically updated to reflect the committed changes.
Owners added a reviewer: Restricted Owners Package.Jul 26 2018, 1:53 PM
Herald added a subscriber: imp. · View Herald TranscriptJul 26 2018, 1:53 PM

Revision Contents
Changeset List

PathSize
head/
usr.bin/
top/
1 line

Diff 45874

View Options

head/usr.bin/top/utils.h

Show First 20 Lines • Show All 45 Lines • ▼ Show 20 Lines
following line in following line in
.Xr loader.conf 5 : .Xr loader.conf 5 :
.Bd -literal -offset indent .Bd -literal -offset indent
snd_uaudio_load="YES" snd_uaudio_load="YES"
.Ed .Ed
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
driver provides support for USB audio class devices and USB MIDI class devices. driver provides support for USB audio class devices and USB MIDI class devices.
emasteUnsubmitted
Done
Inline Actions

probably commit the .Tn removal separately first?

emaste: probably commit the `.Tn` removal separately first?
christosAuthorUnsubmitted
Done
Inline Actions

I thought it's simple enough it can be included here, but I can split it if you want.

christos: I thought it's simple enough it can be included here, but I can split it if you want.
.Pp .Pp
A USB audio device consists of a number of components: input terminals (e.g.\& A USB audio device consists of a number of components: input terminals (e.g.\&
USB digital input), output terminals (e.g.\& speakers), and a number of units USB digital input), output terminals (e.g.\& speakers), and a number of units
in between (e.g.\& volume control). in between (e.g.\& volume control).
.Pp .Pp
If the device supports multiple configurations, and there have been no
user-supplied values specified through the
.Xr sysctl 8
interface, the driver will select the best matching configuration supported by
the device during attach.
"Best" means the configuration with the most channels and highest quality in
dev_submerge.chUnsubmitted
Done
Inline Actions

This paragraph should probably start with the "If a device supports multiple configurations" part, to set the context first. Otherwise people will have to read that very long sentence (break it up?) twice. Also "bits" is vague, I'd use "sample size" here.

dev_submerge.ch: This paragraph should probably start with the "If a device supports multiple configurations"…
sample rate and sample size.
dev_submerge.chUnsubmitted
Done
Inline Actions

This sounds odd. How about "the configuration with the most channels and the highest quality in sample rate and sample size."?

dev_submerge.ch: This sounds odd. How about "the configuration with the most channels and the highest quality in…
.Pp
Refer to the Refer to the
.Ql USB Audio Class Specification .Ql USB Audio Class Specification
for more information. for more information.
.Sh SYSCTL VARIABLES
The following settings can be entered at the
.Xr loader 8
prompt or in
emasteUnsubmitted
Done
Inline Actions

Some man pages have a .Sh LOADER TUNABLES or .Sh SYSCTL VARIABLES

.Sh SYSCTL VARIABLES
The following variables are available as both
.Xr sysctl 8
variables and
.Xr loader 8
tunables:

are all of the variables here sysctls that can also be set as tunables by loader.conf?

emaste: Some man pages have a `.Sh LOADER TUNABLES` or `.Sh SYSCTL VARIABLES` ``` .Sh SYSCTL VARIABLES…
christosAuthorUnsubmitted
Done
Inline Actions

Some man pages have a .Sh LOADER TUNABLES or .Sh SYSCTL VARIABLES

.Sh SYSCTL VARIABLES
The following variables are available as both
.Xr sysctl 8
variables and
.Xr loader 8
tunables:

are all of the variables here sysctls that can also be set as tunables by loader.conf?

Yes.

christos: > Some man pages have a `.Sh LOADER TUNABLES` or `.Sh SYSCTL VARIABLES` > > ``` > .Sh SYSCTL…
.Xr loader.conf 5
and can also be changed at runtime with the
dev_submerge.chUnsubmitted
Done
Inline Actions

I'd give some hint how to apply them, e.g. from vt(4) man page:

These settings can be entered at the loader(8) prompt or in
loader.conf(5) and can also be changed at runtime with the sysctl(8)
command.

Also I wouldn't expect readers to know what variables and tunables are.

dev_submerge.ch: I'd give some hint how to apply them, e.g. from vt(4) man page: ``` These settings can be…
christosAuthorUnsubmitted
Done
Inline Actions

Copied as-is.

christos: Copied as-is.
.Xr sysctl 8
command.
For a change to take effect during runtime, the device has to be re-attached.
emasteUnsubmitted
Done
Inline Actions

This isn't a complete sentence, and I think "boot-time" isn't quite right - based on the description below it is at device attach time?

emaste: This isn't a complete sentence, and I think "boot-time" isn't quite right - based on the…
christosAuthorUnsubmitted
Done
Inline Actions

Yes, this is more correct.

christos: Yes, this is more correct.
.Bl -tag -width indent
dev_submerge.chUnsubmitted
Done
Inline Actions

Wrong. Any of the preferences set here can have an effect on their own, if they match a device's configuration. Although the matching priority is channels > sample size > sample rate, but that's probably too much detail. What did you want to express here?

dev_submerge.ch: Wrong. Any of the preferences set here can have an effect on their own, if they match a…
christosAuthorUnsubmitted
Done
Inline Actions

Perhaps that was a poor choice of words, but I mean that in order for the value we set through the sysctl to take effect (be it rate, channels, bits), it has to be supported (i.e match a valid config) by the device in order to actually be part of the configuration.

christos: Perhaps that was a poor choice of words, but I mean that in order for the value we set through…
dev_submerge.chUnsubmitted
Done
Inline Actions

This is confusing unless very precisely formulated, and it really only concerns the default_* variables. I think the variables are now documented well enough on their own, we could just skip this sentence here.

dev_submerge.ch: This is confusing unless very precisely formulated, and it really only concerns the `default_*`…
.It Va hw.usb.uaudio.buffer_ms
Period of audio data processed at once, in milliseconds, from 1 to 8 (default
is 4).
Lower values mean less latency, but this can result in audible gaps due to
frequent CPU wakeups.
.It Va hw.usb.uaudio.default_bits
christosAuthorUnsubmitted
Done
Inline Actions

@dev_submerge.ch Since we can set higher values than 4 on USB 1.1 devices, maybe the line would be more correct if it was something along the lines of "When set to 0, USB 1.1 devices default to 4 channels due to bandwidth constraints, but higher values can also be set."

christos: @dev_submerge.ch Since we can set higher values than 4 on USB 1.1 devices, maybe the line would…
dev_submerge.chUnsubmitted
Done
Inline Actions
Some devices might need higher values to work proprely.

That's not what I meant. Some devices state in their USB descriptor that they need a longer period to operate. The driver respects that. Thus you can set a lower buffer_ms, but you'll not get the lower latency. Maybe we can just skip this detail, it's confusing.

dev_submerge.ch: ``` Some devices might need higher values to work proprely. ``` That's not what I meant. Some…
Preferred sample size in bits, from 0 to 32 (default is 0).
dev_submerge.chUnsubmitted
Done
Inline Actions

igor says "Lower values" should start on a new line.

dev_submerge.ch: `igor` says "Lower values" should start on a new line.
A value of 0 sets the sample size to the maximum supported sample size.
.Pp
dev_submerge.chUnsubmitted
Done
Inline Actions

I'd use the term "preferred sample size" here, because it reflects that the driver selects from available configurations. But more importantly, we should explicitly state when to use this setting:

Set this to select a smaller sample size if the device supports multiple sample sizes.

It's the only situation this can be useful. Same for channels.

dev_submerge.ch: I'd use the term "preferred sample size" here, because it reflects that the driver selects from…
Set this to select a smaller sample size if the device supports multiple sample
sizes.
.It Va hw.usb.uaudio.default_channels
Preferred number of sample channels, from 0 to 64 (default is 0).
USB 1.1 devices are limited to 4 channels due to bandwidth constraints, unless
a higher value is explicitly requested.
A value of 0 sets the sample channels to the maximum supported channel number.
.Pp
dev_submerge.chUnsubmitted
Done
Inline Actions

How about

USB 1.1 devices are limited to 4 channels due to bandwidth constraints,
unless a higher value is explicitly requested here.
dev_submerge.ch: How about ``` USB 1.1 devices are limited to 4 channels due to bandwidth constraints, unless a…
Set this to select a smaller channel number if the device supports multiple
channel configurations.
dev_submerge.chUnsubmitted
Done
Inline Actions

This part is misleading. If I remember correctly, the driver selects the channel configuration with the most channels by default. It does so by looking for configurations with UAUDIO_CHANNELS_MAX channels, then for UAUDIO_CHANNELS_MAX - 1 channels, and so on until a matching device configuration is found (or 0 is reached). For USB 1.1 devices 4 channels are the maximum, due to bandwidth constraints.
I think the same happens if default_channels is set to, say, 8 - then it tries 8 first, and then 7, 6, 5, and so on.

dev_submerge.ch: This part is misleading. If I remember correctly, the driver selects the channel configuration…
christosAuthorUnsubmitted
Done
Inline Actions

I think we could re-phrase this as:

snd_uaudio will use the maximum channel number supported by the device, starting in descending order, either from UAUDIO_CHANNELS_MAX if hw.usb.uaudio.default_channels is set to 0, or hw.usb.uaudio.default_channels. USB 1.1 devices are limited to 4 channels due to bandwidth constraints.

christos: I think we could re-phrase this as: > snd_uaudio will use the maximum channel number supported…
christosAuthorUnsubmitted
Done
Inline Actions

@dev_submerge.ch Do you think the following is good?

hw.usb.uaudio.default_channels
        Default sample channels, from 0 to UAUDIO_CHANNELS_MAX (default
        is 0).  snd_uaudio will search in descending order for the
        maximum-supported channel configuration, starting either from
        UAUDIO_CHANNELS_MAX if hw.usb.uaudio.default_channels is set to
        0, or, if set to a positive non-zero value, from
        hw.usb.uaudio.default_channels.  USB 1.1 devices are limited to 4
        channels due to bandwidth constraints.
christos: @dev_submerge.ch Do you think the following is good? ``` hw.usb.uaudio.default_channels…
dev_submerge.chUnsubmitted
Done
Inline Actions

I think it's too much implementation detail. E.g., end users probably want to know the limit of 64, not a definition from code. But maybe we can simplify this anyway.

dev_submerge.ch: I think it's too much implementation detail. E.g., end users probably want to know the limit of…
dev_submerge.chUnsubmitted
Done
Inline Actions
Set this to select a smaller channel number if the device supports multiple
sample channels.

"sample channels" still doesn't make sense - how about "if the device supports multiple channel configurations."?

dev_submerge.ch: ``` Set this to select a smaller channel number if the device supports multiple sample channels.
christosAuthorUnsubmitted
Done
Inline Actions

I missed the "sample" while cleaning up the line. My bad.

christos: I missed the "sample" while cleaning up the line. My bad.
.It Va hw.usb.uaudio.default_rate
Preferred sample rate in Hz (default is 0).
dev_submerge.chUnsubmitted
Done
Inline Actions

"sample" channel configurations?

dev_submerge.ch: "sample" channel configurations?
If set to 0, the device's highest supported sample rate will be used.
dev_submerge.chUnsubmitted
Done
Inline Actions

A device doesn't have a default sample rate, AFAIK. The VCHAN setting lets a user choose a sample rate, but with default_rate set, current implementation limits this choice to default_rate max.

dev_submerge.ch: A device doesn't have a default sample rate, AFAIK. The VCHAN setting lets a user choose a…
.Pp
Note that if VCHANs are enabled, the sample rate will be overridden by
.Pa dev.pcm.%d.[play|rec].vchanrate
(see
dev_submerge.chUnsubmitted
Done
Inline Actions

So what is this used for?

dev_submerge.ch: So what is this used for?
christosAuthorUnsubmitted
Done
Inline Actions

I don't really have a way to test this, my device doesn't support this, so I just used the definition from the sysctl description.

christos: I don't really have a way to test this, my device doesn't support this, so I just used the…
dev_submerge.chUnsubmitted
Done
Inline Actions

"overriden" - please do a spell-check again once we're done.

dev_submerge.ch: "overriden" - please do a spell-check again once we're done.
.Xr sound 4 ) ,
which can also be used to adjust the sample rate during runtime.
.Pp
If
.Pa hw.usb.uaudio.default_rate
is non-zero,
.Pa dev.pcm.%d.[play|rec].vchanrate
will use it as its maximum allowed value.
.It Va hw.usb.uaudio.handle_hid
Let
.Nm
handle HID volume keys, if any (default is 1).
.Bl -tag -width 2n
.It 0
Disabled.
.It 1
Enabled.
.El
.El
.Pp
If
.Xr usb 4
has been compiled with
.Va USB_DEBUG
on, the following setting is also available:
.Bl -tag -width indent
.It Va hw.usb.uaudio.debug
Debug output level (default is 0).
.El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sound 4 , .Xr sound 4 ,
.Xr usb 4 .Xr usb 4 ,
.Xr loader.conf 5 ,
.Xr loader 8 ,
.Xr sysctl 8
.Rs .Rs
.%T "USB Audio Class Specifications" .%T "USB Audio Class Specifications"
.%U http://www.usb.org/developers/docs/devclass_docs/ .%U http://www.usb.org/developers/docs/devclass_docs/
.Re .Re
.Sh HISTORY .Sh HISTORY
The The
.Nm .Nm
driver first appeared in driver first appeared in
Show All 19 Lines
rate is configured the same for both recording and playback, even if rate is configured the same for both recording and playback, even if
only simplex is used. only simplex is used.
See the See the
.Va dev.pcm.%d.[play|rec].vchanrate .Va dev.pcm.%d.[play|rec].vchanrate
sysctls. sysctls.
.Pp .Pp
The PCM framework in The PCM framework in
.Fx .Fx
currently doesn't support the full set of USB audio mixer currently does not support the full set of USB audio mixer controls.
controls.
Some mixer controls are only available as Some mixer controls are only available as
.Va dev.pcm.%d.mixer .Va dev.pcm.%d.mixer
sysctls. sysctls.