Merge tag 'trace-v4.21-1' of git://git.kernel.org/pub/scm/linux/kernel/git/rostedt...
[sfrench/cifs-2.6.git] / Documentation / device-mapper / dm-uevent.txt
1 The device-mapper uevent code adds the capability to device-mapper to create
2 and send kobject uevents (uevents).  Previously device-mapper events were only
3 available through the ioctl interface.  The advantage of the uevents interface
4 is the event contains environment attributes providing increased context for
5 the event avoiding the need to query the state of the device-mapper device after
6 the event is received.
7
8 There are two functions currently for device-mapper events.  The first function
9 listed creates the event and the second function sends the event(s).
10
11 void dm_path_uevent(enum dm_uevent_type event_type, struct dm_target *ti,
12                     const char *path, unsigned nr_valid_paths)
13
14 void dm_send_uevents(struct list_head *events, struct kobject *kobj)
15
16
17 The variables added to the uevent environment are:
18
19 Variable Name: DM_TARGET
20 Uevent Action(s): KOBJ_CHANGE
21 Type: string
22 Description:
23 Value: Name of device-mapper target that generated the event.
24
25 Variable Name: DM_ACTION
26 Uevent Action(s): KOBJ_CHANGE
27 Type: string
28 Description:
29 Value: Device-mapper specific action that caused the uevent action.
30         PATH_FAILED - A path has failed.
31         PATH_REINSTATED - A path has been reinstated.
32
33 Variable Name: DM_SEQNUM
34 Uevent Action(s): KOBJ_CHANGE
35 Type: unsigned integer
36 Description: A sequence number for this specific device-mapper device.
37 Value: Valid unsigned integer range.
38
39 Variable Name: DM_PATH
40 Uevent Action(s): KOBJ_CHANGE
41 Type: string
42 Description: Major and minor number of the path device pertaining to this
43 event.
44 Value: Path name in the form of "Major:Minor"
45
46 Variable Name: DM_NR_VALID_PATHS
47 Uevent Action(s): KOBJ_CHANGE
48 Type: unsigned integer
49 Description:
50 Value: Valid unsigned integer range.
51
52 Variable Name: DM_NAME
53 Uevent Action(s): KOBJ_CHANGE
54 Type: string
55 Description: Name of the device-mapper device.
56 Value: Name
57
58 Variable Name: DM_UUID
59 Uevent Action(s): KOBJ_CHANGE
60 Type: string
61 Description: UUID of the device-mapper device.
62 Value: UUID. (Empty string if there isn't one.)
63
64 An example of the uevents generated as captured by udevmonitor is shown
65 below.
66
67 1.) Path failure.
68 UEVENT[1192521009.711215] change@/block/dm-3
69 ACTION=change
70 DEVPATH=/block/dm-3
71 SUBSYSTEM=block
72 DM_TARGET=multipath
73 DM_ACTION=PATH_FAILED
74 DM_SEQNUM=1
75 DM_PATH=8:32
76 DM_NR_VALID_PATHS=0
77 DM_NAME=mpath2
78 DM_UUID=mpath-35333333000002328
79 MINOR=3
80 MAJOR=253
81 SEQNUM=1130
82
83 2.) Path reinstate.
84 UEVENT[1192521132.989927] change@/block/dm-3
85 ACTION=change
86 DEVPATH=/block/dm-3
87 SUBSYSTEM=block
88 DM_TARGET=multipath
89 DM_ACTION=PATH_REINSTATED
90 DM_SEQNUM=2
91 DM_PATH=8:32
92 DM_NR_VALID_PATHS=1
93 DM_NAME=mpath2
94 DM_UUID=mpath-35333333000002328
95 MINOR=3
96 MAJOR=253
97 SEQNUM=1131