Date: Sat, 20 Aug 2005 10:50:19 GMT From: Fredrik Lindberg <fli@shapeshifter.se> To: freebsd-doc@FreeBSD.org Subject: Re: docs/85097: [patch] devd.conf.5 lacks a lot of vital information. Message-ID: <200508201050.j7KAoJg4065842@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/85097; it has been noted by GNATS.
From: Fredrik Lindberg <fli@shapeshifter.se>
To: Giorgos Keramidas <keramida@FreeBSD.org>
Cc: bug-followup@FreeBSD.org, garys@opusnet.com
Subject: Re: docs/85097: [patch] devd.conf.5 lacks a lot of vital information.
Date: Sat, 20 Aug 2005 12:46:52 +0200
This is a multi-part message in MIME format.
--------------050303000707020000020402
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Giorgos Keramidas wrote:
> On 2005-08-19 10:40, Fredrik Lindberg <fli@shapeshifter.se> wrote:
>
>>Gary W. Swearingen wrote:
>>
>>>Some fonts don't show a single "`" well and .Dq seems to be more
>>>popular (and I don't like either one). That is, it's OK.
>>
>>I took a quick look at some other manuals, .Ql seems to be used
>>to quote single characters while .Dq is used to quote words.
>
>
> Correct.
>
>
>>>>+If two statements matches the same event, only the action of the statement with
>>>>+highest priority will be carried out. In this way generic statements can be
>>>>+overridden for devices/notifications that requires special attention.
>>>
>>>IIRC, two sentences should not share the same line.
>>
>> Inserting a hard break between those lines? even though they
>> are so closely related?
>
>
> Yes.
>
>
>> >>+configuration files. Any number of this directive is valid.
>> >
>> >
>> > I'm fairly sure it should "these directives", but "is" is correct.
>> > (I see that it's problematic, though.)
>>
>> I went over that sentence like a 100 times while writing, but since
>> english isn't my native language I really can't say which to use.
>
>
> ``Any number of "foo" directives can be used.'' ?
>
>
>> > Use .Li or .Dq Li or .Ql Li ?
>
>
> The ``.Ql'' request already makes its argument ``literal''. The
> canonical use of ``.Ql'' and ``.Dq Li'' is, AFAIK, one of the following:
>
> .Ql X
> .Dq Li XXX*
>
>
>> >>+The variable $device-name is avaiable for later use with the action-statement.
>> >
>> > Probably: .Va $device-name
>
>
> And a bit of shuffling around. This sounds more natural in English:
>
> The
> .Va device-name
> variable
>
>
>> >>+Command to execute upon a successful match. For example
>> >>+/etc/rc.d/power_profile $notify
>> >
>> > I'd use ".Ic ..." even if it's not interactive. Bold on my term.
>
>
> I would prefer making this a real "display" of literal text that can be
> copy-pasted to the devd.conf file:
>
> .Bd -literal -offset indent
> notify "/etc/rc.d/power_profile $notify";
> .Ed
>
> but this is just a personal preference, I guess.
>
A new patch is attached, that hopefully addresses all issues with
the first.
I also added a some real examples to the EXAMPLES section instead of
just a reference to /etc/devd.conf.
Fredrik Lindberg
--------------050303000707020000020402
Content-Type: text/plain;
name="devd.conf.5-20050820.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="devd.conf.5-20050820.patch"
Index: devd.conf.5
===================================================================
RCS file: /home/ncvs/src/sbin/devd/devd.conf.5,v
retrieving revision 1.8
diff -u -r1.8 devd.conf.5
--- devd.conf.5 3 Mar 2003 11:51:30 -0000 1.8
+++ devd.conf.5 20 Aug 2005 10:29:28 -0000
@@ -41,7 +41,7 @@
.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
.\" SOFTWARE.
.\"
-.Dd October 17, 2002
+.Dd August 20, 2005
.Dt DEVD.CONF 5
.Os
.Sh NAME
@@ -61,18 +61,21 @@
The following statements are supported:
.Bl -tag -width ".Ic options"
.It Ic options
-specifies various options and parameters for the operation of
+Specifies various options and parameters for the operation of
.Xr devd 8 .
.It Ic attach
-specifies various matching criteria and actions to perform when
+Specifies various matching criteria and actions to perform when
a newly attached device matches said criteria.
.It Ic detach
-specifies various matching criteria and actions to perform when
+Specifies various matching criteria and actions to perform when
a newly detached device matches said criteria.
.It Ic nomatch
-specifies various matching criteria and actions to perform when
+Specifies various matching criteria and actions to perform when
no device driver currently loaded in the kernel claims a (new)
device.
+.It Ic notify
+Specifies various matching criteria and actions to perform when the kernel
+sends an event notification to userland.
.El
.Pp
Statements may occur in any order in the configuration file, and may be
@@ -80,6 +83,229 @@
Further details on the syntax and meaning of each statement and their
substatements are explained below.
.Pp
+Each statement, except
+.Dq options
+has a priority (an arbitrary number) associated with it, where
+.Ql 0
+is defined as the lowest priority.
+If two statements match the same event, only the action of the statement with
+highest priority will be executed.
+In this way generic statements can be overridden for devices or
+notifications that require special attention.
+.Pp
+The general syntax of a statement is:
+.Pp
+.Bd -literal -offset indent
+statement priority {
+ substatement "value";
+ ...
+ substatement "value";
+};
+.Ed
+.Pp
+.Ss Sub-statements
+The following sub-statements are supported within the
+.Dq options
+statement.
+.Bl -tag -width ".Ic directory"
+.It Ic directory \*q/some/path\*q;
+Adds the given directory to the list of directories from which
+.Xr devd 8
+will read
+configuration files. Any number of
+.Dq directory
+statements can be used.
+.It Ic pid-file \*q/var/run/devd.pid\*q;
+Specifies pid file.
+.It Ic set regexp-name \*q(some|regexp)\*q;
+Creates a regular expression and assigns it to the variable
+.Va regexp-name
+; this variable is then avaiable throughout the rest of
+the configuration file.
+All regular expressions have an implicit
+.Ql Li ^$
+around them.
+.El
+.Pp
+The following sub-statements are supported within the
+.Dq attach
+and
+.Dq detach
+statements.
+.Bl -tag -width ".Ic directory"
+.It Ic device-name \*qstring\*q;
+Actually a shorthand to
+.Dq match device-name
+Matches a device named
+.Va string
+; which are allowed to be a regular expression or a variable previously created
+containing a regular expression.
+The
+.Va device-name
+variable
+is avaiable for later use with the action-statement.
+.It Ic match \*qvariable\*q \*qvalue\*q;
+Matches the content of
+.Va value
+against
+.Va variable
+, the content of
+.Va value
+may be a regular expression.
+Not really needed during
+.Dq Li attach
+nor
+.Dq Li detach
+events since the
+.Dq Li device-name
+statement takes care of all device matching.
+For a partial list of variables, see below.
+.It Ic action \*qcommand\*q;
+Command to execute upon a successful match.
+Example
+.Ic /etc/pccard_ether $device-name start
+.El
+.Pp
+The following sub-statements are supported within the
+.Dq nomatch
+statement.
+.Bl -tag -width ".Ic directory"
+.It Ic match \*qvariable\*q \*qvalue\*q;
+Matches the content of
+.Va value
+against
+.Va variable
+, the content of
+.Va value
+may be a regular expression.
+For a partial list of variables, see below.
+.It Ic action \*qcommand\*q;
+Same as above.
+.El
+.Pp
+The following sub-statements are supported within the
+.Dq notify
+statement.
+The
+.Dq Li notify
+variable is avaiable inside this statement and contains, a value, depending
+on which system and subsystem that delivered the event.
+.Bl -tag -width ".Ic directory"
+.It Ic match \*qsystem|subsystem|type|notify\*q \*qvalue\*q;
+Any number of
+.Dq match
+statements can exists within a
+.Dq notify
+statement.
+.Va value
+can be either a fixed string or a regular expression.
+Below is a list of avaiable systems, subsystems, and types.
+.It Ic action \*qcommand\*q;
+Command to execute upon a successful match. Example
+.Ic /etc/rc.d/power_profile $notify
+.El
+.Ss Variables that can be used with the match statement
+A partial list of variables and their possible values that can be used together
+with the
+.Dq match
+statement.
+.Pp
+.Bl -tag -width "manufacturer" -compact
+.It Ic Variable
+.Ic Possible value
+.It system
+Matches a system type, see below
+.It subsystem
+Matches a subsystem of a system, see below
+.It type
+Type of notification, see below
+.It notify
+Match the value of the
+.Dq Li notify
+variable.
+.It device-name
+Name of attached/detached device
+.It bus
+pccard[0-9]+, cardbus[0-9]+
+.It vendor
+Vendor ID
+.It device
+Device ID
+.It subvendor
+Sub-vendor ID
+.It subdevice
+Sub-device ID
+.It class
+Device class
+.It slot
+Card slot
+.It function
+Card functions
+.It manufacturer
+Manufacturer ID (pccard)
+.It product
+Product ID (pccard)
+.It cisvendor
+CIS-vendor
+.It cisproduct
+CIS-product
+.El
+.Ss Notify matching
+A Partial list of systems, subsystems, and types used within the
+.Dq notify
+mechanism.
+.Pp
+.Bl -tag -width "IFNET" -compact
+.It Ic System
+.It ACPI
+Events related to the ACPI subsystem.
+.Bl -tag -compact
+.It Ic Subsystem
+.It ACAD
+AC Line state ($notify=0x00 is offline, 0x01 is online).
+.It Button
+Button state ($notify=0x00 is power, 0x01 is sleep).
+.It CMBAT
+Battery events.
+.It Lid
+Lid state ($notify=0x00 is closed, 0x01 is open).
+.It Thermal
+Thermal zone events.
+.El
+.Pp
+.It IFNET
+Events related to the network subsystem.
+.Bl -tag -compact
+.It Ic Subsystem
+.It [interface]
+The
+.Dq subsystem
+is the actual name of the network interface on which the event
+took place.
+.Bl -tag -compact
+.It Ic Type
+.It LINK_UP
+Carrier status changed to UP.
+.It LINK_DOWN
+Carrier status changed to DOWN.
+.El
+.El
+.El
+.Pp
+A link state change to UP on the interface
+.Dq fxp0
+would result in the following notify event:
+.Bd -literal -offset indent
+system=IFNET, subsystem=fxp0, type=LINK_UP
+.Ed
+.Pp
+An AC line state change to
+.Dq offline
+would result in the following event:
+.Bd -literal -offset indent
+system=ACPI, subsystem=ACAD, notify=0x00
+.Ed
+.Ss Comments
Comments may appear anywhere that whitespace may appear in a
configuration file.
To appeal to programmers of all kinds, they can
@@ -110,7 +336,7 @@
(slash, slash) and continue to the end of the physical line.
They cannot be continued across multiple physical lines; to have
one logical comment span multiple lines, each line must use the
-.Ql //
+.Dq //
pair.
For example:
.Bd -literal -offset indent
@@ -118,6 +344,59 @@
// is a new comment, even though it is logically
// part of the previous comment.
.Ed
+.Sh EXAMPLES
+.Bd -literal
+#
+# This will catch link down events on the interfaces fxp0 and ath0
+#
+notify 0 {
+ match "system" "IFNET";
+ match "subsystem" "(fxp0|ath0)";
+ match "type" "LINK_DOWN";
+ action "logger $subsystem is DOWN";
+};
+
+#
+# Match lid open/close events
+# These can be combined to a single event, by passing the
+# value of $notify to the external script.
+#
+notify 0 {
+ match "system" "ACPI";
+ match "subsystem" "Lid";
+ match "notify" "0x00";
+ action "logger Lid closed, we can sleep now!";
+};
+
+notify 0 {
+ match "system" "ACPI";
+ match "subsystem" "Lid";
+ match "notify" "0x01";
+ action "logger Lid opened, the sleeper must awaken!";
+};
+
+#
+# Try to configure ath and wi devices with pccard_ether
+# as they are attached.
+#
+attach 0 {
+ device-name "(ath|wi)[0-9]+";
+ action "/etc/pccard_ether $device-name start";
+};
+
+#
+# Stop ath and wi devices as they are detached from
+# the system.
+#
+detach 0 {
+ device-name "(ath|wi)[0-9]+";
+ action "/etc/pccard_ether $device-name stop";
+};
+.Ed
+.Pp
+The installed
+.Pa /etc/devd.conf
+has many additional examples.
.Sh FILES
.Bl -tag -width ".Pa /etc/devd.conf" -compact
.It Pa /etc/devd.conf
--------------050303000707020000020402--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200508201050.j7KAoJg4065842>