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