spec.v1.txt

网络数据管理协议的开发

   NDMP_ILLEGAL_ARGS_ERR Specified backup type not supported.


3.3 SCSI Interface

The SCSI interface allows low level control of SCSI devices such as
jukeboxes.


3.3.1 Open SCSI Device

Opens the specified SCSI interface device. This operation is required
before any other SCSI requests can be executed. The open must be an
exclusive open.  Only one NDMP server can open a SCSI device at a time.
The NDMP server can only open one SCSI or tape device at a time. A


Stager,Hitz                                                    Page 30





Internet Draft     Network Data Management Protocol       October 1996


NDMPDeviceBusy is returned if the NDMP server already has a tape or SCSI
device opened.



   struct ndmp_scsi_device
   {
       string  name<>;
   };

   struct ndmp_scsi_open_request
   {
       ndmp_scsi_device    device;
   };

   struct ndmp_scsi_open_reply
   {
       ndmp_error  error;
   };



Request Arguments


   name                  Name of SCSI interface device to open.  The usage
                         of this argument is NDMP server implementation
                         dependent.  This argument may be used to specify
                         the name of an  actual SCSI device but more
                         typically will be used to specify the name of a
                         SCSI pass-through driver pseudo device. The
                         specific device to be controlled is selected via
                         the set SCSI target request.


Reply Arguments


   error                 Error code.


Reply Errors


   NDMP_NO_ERR           SCSI interface device successfully opened.


   NDMP_DEVICE_OPENED_ERRThe connection already has a tape device or SCSI
                         device open.




Stager,Hitz                                                    Page 31





Internet Draft     Network Data Management Protocol       October 1996


   NDMP_NO_DEVICE_ERR    Invalid device specified.


   NDMP_DEVICE_BUSY_ERR  Another NDMP connection currently has the
                         specified device open.


   NDMP_IO_ERR           IO error while opening SCSI device.





3.3.2 Close Device

Closes the currently open SCSI interface device.  No further requests can
be until another open request is successfully executed.


Message XDR definition



   /* no request arguments */
   struct ndmp_scsi_close_reply
   {
       ndmp_error  error;
   };




Request Arguments


   This request does not have a message body.


Reply Arguments


   error                 Error code.


Reply Errors


   NDMP_NO_ERR           Device successfully closed.


   NDMP_DEV_NOT_OPEN_ERR No device currently open by the connection.


Stager,Hitz                                                    Page 32





Internet Draft     Network Data Management Protocol       October 1996


3.3.3 Get SCSI State

Return the current state of the currently open SCSI interface. The target
information provides information about which SCSI device is controlled by
this interface.


Message XDR definition



   /* No request message body. */

   struct ndmp_scsi_get_state_reply
   {
       ndmp_error          error;
       short               target_controller;
       short               target_id;
       short               target_lun;
   };



Request Arguments


   This request does not have a message body.


Reply Arguments


   error                 Error code.


   target_controller     Identifier of the SCSI controller to which the
                         currently targeted SCSI device is attached.


   target_id             SCSI target identifier. Specifies the SCSI bus
                         address of the targeted device.


   target_lun            Logic unit number of the targeted device.


Reply Errors


   NDMP_NO_ERR           Target device information successfully returned.



Stager,Hitz                                                    Page 33





Internet Draft     Network Data Management Protocol       October 1996


   NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the connection.


3.3.4 Set SCSI Target

Selects or changes the SCSI target. When the SCSI interface is opened, we
do not know if the NDMP server has opened a device file that can pass
commands to a single SCSI target or to multiple SCSI targets. This part of
protocol allows us to pass the information describing the SCSI target to
which to send commands. Additionally, if the target can talk to multiple
targets, this allows us to _scan_ the SCSI bus on the NDMP host for
diagnostics or the jukebox discovery.


Message XDR definition



   struct ndmp_scsi_set_target_request
   {
       ndmp_scsi_device    device;
       u_short             target_controller;
       u_short             target_id;
       u_short             target_lun;
   };

   struct ndmp_scsi_set_target_reply
   {
       ndmp_error  error;
   };




Request Arguments


   device                SCSI device name. This argument is NDMP server
                         implementation dependent. Some implementations
                         may support the targeting of a device via a
                         logical device name. If this argument is used,
                         the following  arguments may be ignored. If this
                         argument is not specified or supported, then the
                         following arguments must be specified.


   target_controller     Identifier of the SCSI controller to which the
                         targeted SCSI device is attached.





Stager,Hitz                                                    Page 34





Internet Draft     Network Data Management Protocol       October 1996


   target_id             SCSI target identifier. Specifies the SCSI bus
                         address of the targeted device.


   target_lun            Logic unit number of the targeted device.


Reply Arguments


   error                 Error code. 


Reply Errors


   NDMP_NO_ERR           Specified SCSI device successfully targeted.


   NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the connection.


3.3.5 Reset Device

Send a SCSI device reset message to the SCSI device.


Message XDR definition



   /* No request message body. */

   struct  ndmp_scsi_reset_device_reply
   {
       ndmp_error          error;
   }




Request Arguments


   This request does not have a message body.


Reply Arguments


   error                 Error code.


Stager,Hitz                                                    Page 35





Internet Draft     Network Data Management Protocol       October 1996


Reply Errors


   NDMP_NO_ERR           SCSI device successfully reset.


   NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the connection


3.3.6 Reset Bus

Assert a SCSI bus reset on the SCSI bus to which the SCSI device is
attached.



   /* No request message body. */

   struct  ndmp_scsi_reset_bus_reply
   {
       ndmp_error          error;
   }



Request Arguments


   This request does not have a message body.


Reply Arguments


   error                 Error code.


Reply Errors


   NDMP_NO_ERR           SCSI device successfully reset.


   NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the connection


3.3.7 Execute CDB

Send a SCSI Control Data Block to a SCSI device. If a check condition is
generated, then the extended sense data is also retrieved. Data can be
transferred to or from the SCSI device as part of the command.


Stager,Hitz                                                    Page 36





Internet Draft     Network Data Management Protocol       October 1996


The server selects the SCSI target. The cdb is sent to the SCSI device in
command mode. If DATA_OUT is set in the flags, then the data_out is sent
to the SCSI device in data mode. Sometimes, the host will disconnect from
the target and waits for a re-select. If timeout is zero then the host
will wait indefinitely for the target to re-select. If timeout is non-zero
then the host will wait timeout milliseconds for the target to reselect.
If the reselect does not occur then an NDMPTimeout exception occurs. If
the target re-selects and the status is CHECK CONDITION, then the server
executes a REQUEST SENSE cdb.   If the DATA_IN flag is set, then server
gets data from the target in a data mode and datain_len and dataout_len
are set to indicate the expected data length. The SCSI status, the data in
and the extended sense data is returned.


DATA_IN and DATA_OUT are with reference to the host. They refer to data
from the SCSI device into the host and data out of the host and to the
SCSI device.


Message XDR definition



   /* SCSI CDB flags */
   const   NDMP_SCSI_DATA_IN   = 0x00000001;
   const   NDMP_SCSI_DATA_OUT  = 0x00000002;

   struct  ndmp_execute_cdb_request
   {
       u_long      flags;
       u_long      timeout;
       u_long      alloc_len;
       opaque      cdb<>;
       opaque      dataout<>;
   };

   struct  ndmp_execute_cdb_reply
   {
       ndmp_error  error;
       u_char      status;
       u_long      dataout_len;
       opaque      datain<>;
       opaque      ext_sense<>;
   };




Request Arguments




Stager,Hitz                                                    Page 37





Internet Draft     Network Data Management Protocol       October 1996


   flags                 Specifies the data transfer (if any) direction.


   timeout               Number of milliseconds to wait if a re-select
                         occurs. If timeout is zero then the host will
                         wait  indefinitely for the target to reselect.


   alloc_len             If the data tranfer direction is DATA_IN, the
                         expected number of data bytes that will be
                         received.


   cdb                   The SCSI command data block.


   dataout               If the data transfer direction is DATA_OUT, the
                         data to be transfered to the SCSI device.


Reply Arguments


   error                 Error code.


   status                SCSI status byte.


   data_out              If the data transfer direction is DATA_OUT, the
                         number of data bytes transfered to the device.


   datain                If the data transfer direction is DATA_IN, the
                         data transfered from the SCSI device.


   ext_sense             Extended SCSI sense data.


Reply Errors


   NDMP_NO_ERR           Message successfully processed. Does not
                         necessarily indicate that the SCSI command was
                         successfully executed. The returned SCSI status
                         byte must be used to determine if the command was
                         successful.


   NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the connection.


Stager,Hitz                                                    Page 38





Internet Draft     Network Data Management Protocol       October 1996


   NDMP_NO_DEVICE_ERR    A SCSI device has not yet been targeted via the
                         set SCSI target message.


   NDMP_ILLEGAL_ARGS     Invalid argument in request message.


   NDMP_TIMEOUT_ERR      The SCSI command timed out.


   NDMP_NO_BUS_ERR       The SCSI currently specified controller (as set
                         via the set SCSI target message) does not exist.


3.4 TAPE Interface

Provide complete control of a tape drive. If the tape drive is a SCSI tape
drive, then this interface also  provides low level CDB access to the tape
drive. This interface is analogous to the rmt protocol.   The physical
device is assigned when the server is started.


3.4.1 Open Tape Device

Opens the tape device in the specified mode.  This operation is required
before any other tape requests can be  executed. The device is opened
exclusively.  Each tape device may only be opened by one NDMP server at a
time. Each NDMP server may only have one tape or SCSI device open at a
time. If the drive does not have a tape loaded, an error is returned. If
the loaded media is write protected, then the device  may only be opened
in read only mode.


Message XDR definition



















Stager,Hitz                                                    Page 39





Internet Draft     Network Data Management Protocol       October 1996




   enum struct ndmp_tape_device
   {
       string  name<>;
   };

   ndmp_tape_open_mode
   {
       NDMP_TAPE_READ_MODE,
       NDMP_TAPE_WRITE_MODE
   };

   struct ndmp_tape_open_request
   {
       ndmp_tape_device    device;
       ndmp_tape_open_mode mode;
   };

   struct ndmp_tape_open_reply
   {
       ndmp_error          error;
   };