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

[Kevin Corry]

On Tuesday 29 April 2003 08:55, Alasdair G Kergon wrote:
> 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

All of the recent changes look good (the multiple-majors stuff in particular)! 
My only question is: shouldn't the ioctl version be increased to 4.0.0? About 
a month ago, the ioctl packet definition was updated to use a 64-bit dev_t, 
and the version was set to 3.0.0 (see revision 1.18 of dm-ioctl.h). As of 
today, the version is at 3.0.6, but with the above change in the definition 
of struct dm_ioctl, it doesn't seem to be backwards-compatible with the 3.0.0 
version (as per the comments embedded in that structure's definition). In 
addition, some of the externally-visible behavioral changes (e.g. #2 and #5 
above) also do not seem backwards-compatible. Any chance the version can be 
bumped to 4.0.0?

-- 
Kevin Corry
kevcorry at us.ibm.com
http://evms.sourceforge.net/