[dm-devel] device-mapper ioctl interface version 3

[Alasdair G Kergon]

We're almost ready to release version 3 of the ioctl interface now, as
per CVS head.  The changes are designed to improve the flexibility and
efficiency of the use of the interface, and at the same time address a
few problems that showed up in the original version.


struct dm_ioctl {
	uint32_t version[3];	/* in/out */
	uint32_t data_size;	/* total size of data passed in
				 * including this struct */

	uint32_t data_start;	/* offset to start of data
				 * relative to start of this struct */

	uint32_t target_count;	/* in/out */
	int32_t open_count;	/* out */
	uint32_t flags;		/* in/out */
	uint32_t event_nr;      /* in/out */
	uint32_t padding;

	uint64_t dev;		/* in/out */

	char name[DM_NAME_LEN];	/* device name */
	char uuid[DM_UUID_LEN];	/* unique identifier for
				 * the block device */
};


Summary of the main changes:

  1)  Incorrect field alignments fixed.  [As per EVMS interface version 2.]

  2)  All commands now return ENXIO if asked to operate on a device 
that can't be found - DM_EXISTS_FLAG is no longer set. [The flag is
untouched.]

  3)  Most commands now fill in the output fields (like Info does) on
success before returning.  (Not filled when returning an error code.)

  4)  Suspend & Resume no longer fail if the device is already in the
requested state. [And can confirm the state because of (3).]

  5) If the supplied buffer wasn't big enough for all the output,
DM_BUFFER_FULL_FLAG gets set.  Status & table return the first part of
the data.  Deps doesn't [may change].

  6)  On return, data_size is set to the actual amount of data returned.
data_size gets set to 0 if only the version number was filled in [this
inconsistency may get changed].  It's set to sizeof(struct dm_ioctl)
if the output fields were filled in, and a larger number if further
output was supplied e.g. for status, table, deps & wait.  So after
checking ioctl() hasn't returned an error, data_size can be used to
check whether the output (info) fields were filled in, and how much
data was actually returned.  (If you're using one buffer for successive
system calls, you'll need to reset data_size back up to the buffer
size each time.)

  7)  New 'event number' field to avoid race.  Events are now
registered against devices.  The event number is set to 0 when the
device is created, and gets incremented whenever an event against one of
the device's targets occurs.  When asked to wait for an event, if the
event number passed in is less than the current event number, the 
system call returns immediately.  The new event number is reported
for use as input to subsequent calls [because of (3)].

  8) Wait now performs Status or Table (according to
DM_STATUS_TABLE_FLAG) before returning and after the event has been
triggered and *after* filling in the new event number field.

  9) device fields increased to 64 bits in case required in future.

 10) DM_PERSISTENT_DEV_FLAG takes note of the supplied major number too.
If device-mapper has not already requested use of that major number, it
does so and reserves it for future requests made with this flag set.


Alasdair
-- 
agk at uk.sistina.com