dm-uevent.rst

  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