ITBU(4) AIX ITBU(4) NAME itbu - AIX PS/2 Internal Tape Backup Unit Interface DESCRIPTION The files rst0, rst4, rst8, and rst12 refer to the PS/2 Internal Tape Backup Units connected to the floppy disk con- troller. The following description applies to all PS/2 Internal Tape Backup Units using the AIX PS/2 Internal Backup Unit Device Driver. The file rst0 is neither reten- tioned nor rewound on open but is rewound on close. rst4 is neither retentioned nor rewound on open or close. rst8 is retentioned and rewound on open and rewound on close. rst12 is retentioned and rewound on open and not rewound on close. Only one Internal Tape Backup Unit will be recognized in a system. The floppy drive may not be used concurrently with the PS/2 Internal Tape Backup Unit. The device driver maintains the tape position but will rewind the tape on the first open after a tape has been removed and reinserted or when a new tape is inserted. Similarly, if AIX is rebooted the tape will be rewound. If a device is to be closed and the last operation on the device was a write, then two filemarks are written. If the tape is not to be rewound on close, then the head is effec- tively positioned between the two filemarks. If a device is to be closed and the last operation on the device was a read, the tape is not to be rewound, and the last read did not read a filemark, then the tape is spaced forward to the EOT side of the next filemark. A number of ioctl operations are available on the tape drive. Note that the tape IOCTL operations are only valid for the rst20x files. These IOCTL operations are ignored for the Disk like devices. The following definitions are in : Commands are issued through ioctl by passing MTIOCTOP as the command and a pointer to the following structure as the argument: struct mtop { short mt_op; /* operations defined below */ daddr_t mt_count; /* how many of them */ }; The following are valid operations (mt_op) for PS/2 Internal Tape Backup Unit and most other magnetic tape drives: MTWEOF writes n filemarks at the current position. The device must be opened for write or the process Rev. May 8, 1989 Page 1 ITBU(4) AIX ITBU(4) must have an effective user ID of that of the superuser to issue this ioctl. MTFSF forward positions the tape mt_count filemarks. (negative numbers are allowed to backspace file- marks.) MTBSF backward positions the tape mt_count filemarks. MTFSR forward skips mt_count (1K) records. MTBSR backward skips mt_count (1K) records. MTREW rewinds tape and positions the head on track 0 (mt_count ignored). MTOFFL rewinds tape and positions the head on track 0 (mt_count ignored). MTNOP no operation, sets status only (mt_count ignored). The ioctls defined in may also be used with the AIX PS/2 Internal Tape Backup Unit Device Driver. The self test (RAS) operations are ignored and STRESET performs the same function as MTOFFL. STERASE erases only the filemark map and the first 29K of data (the device must be opened for write or the process must have an effective user ID of that of the superuser to issue this ioctl). STRETEN retentions the tape. The standard AIX Info ioctls are supported, and return parameters relevant to a floppy disk with 1K sectors. Only limited support is provided for MTIOCGET and STIOCGET which both return 0's in all elements of their structures. Each read or write call reads or writes an integral number of 1K sectors on the tape. When using raw tape devices seeks are allowed (and ioctls may also be used to position the tape.) A zero byte count is returned when a filemark is read, but another read will fetch the first record of the new tape file. Filemarks have a BOT (beginning of tape) and an EOT (end of tape) side. Forward positioning to a filemark will leave the head on the EOT side of the filemark, while reverse positioning will leave the head on the BOT side. Reading one record, skipping forward one filemark (or block) from the BOT side of a filemark will leave the head on the EOT side of the same filemark (and skipping back one filemark, or block, from the EOT side of a filemark will leave the head on the BOT side of the same filemark). The files st0, st4, st8, and st12, are block devices that behave similarly to the raw devices but use kernel buffer- ing. They are not normally used for backup or archival pur- poses. The files rst100, rst104, rst108, and rst112 behave more like a disk. None of the tape ioctls are supported on these devices and no filemarks are written nor detected. The same Rev. May 8, 1989 Page 2 ITBU(4) AIX ITBU(4) minor device number considerations apply, but on open the first read will always read the first data block on the tape. These files may allow some foreign tapes to be read and/or written. The files rst200, rst204, rst208, and rst212 behave a little more like a tape. IOCINFO ioctls return DD_TAPE instead of DD_DISK, and seeks are ignored on the raw devices. The same minor device number considerations apply. These devices are provided for programs which may not function properly on this tape device when IOCINFO returns DD_DISK. USING BACKUP, CPIO, TAR and TCTL The PS/2 Internal Tape Backup Unit is unique in that it has a fixed number of blocks, the blocks are 1K in size, and it appears more like a disk than a tape. For this reason options on some commands may not be supported. When using the backup command the -C option will be ignored and -s options cannot be used. The -l option is supported when the number of blocks is a multiple of the cluster size (464 blocks). You must specify the PS/2 Internal Tape Backup Unit with the -f option (e.g. -f/dev/rst0). For example: find . -print | backup -ivf/dev/rst0 It is best to use a "200 series" minor device (e.g. /dev/rst204) to restore a tape backed up with a "0 series" (best for backup) minor device (e.g. /dev/rst0). Use of the "0 series" minor device number can, under some cir- cumstances, cause a "READ ERROR on sector ####, assuming zeros" error message to be reported, but should not affect the data being restored. When using the cpio command the -B option (5120 byte blocks) or -C option (specified with an even number of blocks) must be used. The default 512 byte blocks are not a multiple of the PS/2 Internal Tape Backup Unit's block size and there- fore cannot be used. For example: find . -print | cpio -ovB > /dev/rst0 When using the tar command the -u and -r options are not supported. The -b option must specify an argument which is even. You must specify the PS/2 Internal Tape Backup Unit with the -f option (e.g. -f/dev/rst0). For example: tar -cvf/dev/rst0 . When using the tctl command you must specify the PS/2 Inter- nal Tape Backup Unit with the -f option specifying the no- Rev. May 8, 1989 Page 3 ITBU(4) AIX ITBU(4) rewind device (e.g. -f /dev/rst4). You must be superuser to use the erase, eof, or weof tctl operations. Ras1 and ras2 are not supported on the PS/2 Internal Tape Backup Unit. Erase erases only the first 29K of user data and filemark map. For example, to rewind the tape: tctl -f /dev/rst4 rewind PERFORMANCE Better performance may be achieved by using the dd command in combination with backup, cpio, or tar. The use of dd will prevent proper handling of end-of-tape conditions, so care must be taken to ensure that all data to be backed up will fit on one tape. To keep the tape streaming, large block sizes should be avoided. The tape uses 29K blocks inter- nally and small multiples of this number are best to use with dd (e.g. 58k). Sample commands using dd: find . -print | backup -ivf- | dd bs=58k of=/dev/rst0 find . -print | cpio -ovC64 | dd bs=64b of=/dev/rst0 tar -cvf- . | dd bs=16b of=/dev/rst0 INTERNALS Tapes must both be servo written and formatted prior to use. Preformatted tapes are available. There is no facility for formatting tapes using the AIX PS/2 Internal Tape Backup Unit Device Driver. The first block on the tape holds data about the tape format and the bad block map. This header information is written four times with ECC in the first block of the tape. If this information is damaged or destroyed such that none of the four headers can be read, then the open will fail. A filemark map is held on the second block of the tape. The filemark map holds the location of up to 1024 filemarks. It is a list of four-byte sector numbers terminated by a -1. These sector numbers are treated as filemarks and data on the tape where the filemarks are located is undefined. Tapes which have been rewritten many times can sometimes contain many filemarks between the end of the data and the end of tape. Issuing an STERASE ioctl or issuing a "tctl erase" command will erase the filemark map. If an attempt is made to write too many filemarks to the tape, the driver will return ENOSPC and log the message "filemark table over- flow" to /dev/osm. Rev. May 8, 1989 Page 4 ITBU(4) AIX ITBU(4) Data starts on fourth block of the tape. The third block is presently not used. It is not possible to directly read or write the first three information blocks on the tape. All reads and writes start on the fourth block. The device driver generates 3K of ECC (Error Correction Code) data for each 29K of user data. The ECC is used to attempt to regenerate lost data due to undetected errors in writing or damage to the tape. The ECC is capable of regen- erating up to three 1K sectors within a 32K block. The drive does not do read after write for performance reasons and because, with the ECC, good error rates can be achieved without it. Because of the need to generate ECC data based on 29K of user data, data must be buffered within the driver. This is also done for performance reasons and makes it possible to keep the tape streaming. ERROR LOGGING Error messages are sent on almost all failed commands to /dev/osm. The error messages since system startup can be seen by "cat"ing /dev/osm. All error messages from the AIX PS/2 Internal Tape Backup Unit Device Driver are prefixed by "Internal Tape:". Many non-fatal error messages are logged, including all blocks on which ECC decoding was necessary because of a CRC error in the data. Fatal errors cause sys- tem calls to return -1 and the type of error is available to the application program in errno. Less serious errors, such as no tape in the drive, are written only to the users ter- minal. They are not logged to /dev/osm. In addition to those errors listed in ioctl, open, read, and write, system calls against this device fail in the follow- ing circumstances: ENXIO Invalid minor device number, or Internal Tape Backup Unit not present. EBUSY Internal Tape Backup Unit is currently in use, or floppy drive is in use. EIO No tape is installed in Internal Tape Backup Unit, or the Internal Tape Backup Unit is not responding to commands, or an unformatted tape is in the drive, or the tape has too many data errors. EWRPROTECT A write protected cartridge is installed, or a tape with a format which cannot be written is installed. EFAULT An invalid address was passed as an argument to a system call, or an invalid read or write length was given. EINVAL An invalid ioctl request was given. Rev. May 8, 1989 Page 5 ITBU(4) AIX ITBU(4) ENOMEM Not enough memory could be allocated to perform the requested action. ENOSPC A read or write write attempted to read/write beyond the end of tape, or an attempt to write a filemark failed because the filemark map was full. EACCES An attempt was made to issue an ioctl to erase, write filemarks, or format the tape when the device was not opened for write or the process did not have an effective user ID of that of the superuser. FILES /dev/st* /dev/rst* RELATED INFORMATION The following commands: open, close, read, write, ioctl, backup, cpio, devices, restore, tar, and tctl. LIMITATIONS Because of a hardware bug in the NEC 765 controller chip, DMA overruns are sometimes not detected and may cause data to be incorrectly written on the tape. If a DMA overrun is detected (~99.9% of all DMA timeouts should be detected), writing will fail. Use of third party display adapters is the primary cause of DMA timeouts. If you are experiencing DMA overrun errors (logged in /dev/osm, see ERROR LOGGING above), there is a chance that your tapes may be written with unreadable data when no DMA timeout error occurs. If this happens, on read a error will be returned (EIO) and the message "blank tape encountered" will be logged to /dev/osm. Screen I/O is usually the problem with third party display adapters and in such cases screen I/O should not be done while the tape is being written (do not use the -v flag on backup, tar, or cpio, or redirect output to a file, or change to an inactive virtual terminal.) Tape should always be verified after writing. This can be done by checking for a zero return code from dd while read- ing the section of the tape which was just written. For example: dd if=/dev/rst0 of=/dev/null bs=4k The -T option on restore, or the -t option on cpio or tar may also be used to verify that the tape was written correctly. Reads and writes must be a multiple of 1K bytes and the data Rev. May 8, 1989 Page 6 ITBU(4) AIX ITBU(4) must be aligned on a page boundary. Because data is buffered within the drive, write errors will often not be reported until one or two writes later or on close. Rev. May 8, 1989 Page 7