tape: improve code docs

src/tape/drive/linux_tape.rs

@@ -1,3 +1,5 @@
+//! Driver for Linux SCSI tapes
+
 use std::fs::{OpenOptions, File};
 use std::os::unix::fs::OpenOptionsExt;
 use std::os::unix::io::{AsRawFd, FromRawFd};
@@ -49,12 +51,18 @@ use crate::{
     }
 };
 
+/// Linux tape drive status
 #[derive(Debug)]
 pub struct LinuxDriveStatus {
+    /// Size 0 is variable block size mode (default)
     pub blocksize: u32,
+    /// Drive status flags
     pub status: GMTStatusFlags,
+    /// Tape densitiy code (if drive media loaded)
     pub density: Option<TapeDensity>,
+    /// Current file position if known (or -1)
     pub file_number: Option<u32>,
+    /// Current block number if known (or -1)
     pub block_number: Option<u32>,
 }
 

src/tape/drive/mam.rs

@@ -114,6 +114,7 @@ fn read_tape_mam<F: AsRawFd>(file: &mut F) -> Result<Vec<u8>, Error> {
         .map(|v| v.to_vec())
 }
 
+/// Read Medium auxiliary memory attributes (cartridge memory) using raw SCSI command. 
 pub fn read_mam_attributes<F: AsRawFd>(file: &mut F) -> Result<Vec<MamAttribute>, Error> {
 
     let data = read_tape_mam(file)?;

src/tape/drive/mod.rs

@@ -269,6 +269,7 @@ pub fn required_media_changer(
     }
 }
 
+/// Opens a tape drive (this fails if there is no media loaded)
 pub fn open_drive(
     config: &SectionConfigData,
     drive: &str,

src/tape/drive/volume_statistics.rs

@@ -58,6 +58,8 @@ struct LpParameterHeader {
     parameter_len: u8,
 }
 
+
+/// Volume statistics from SCSI log page 17h
 #[derive(Default, Serialize, Deserialize)]
 pub struct Lp17VolumeStatistics {
     pub volume_mounts: u64,

src/tape/file_formats.rs

@@ -1,3 +1,5 @@
+//! File format definitions for data written to tapes
+
 use std::collections::HashMap;
 
 use anyhow::{bail, Error};

src/tape/media_catalog.rs

@@ -29,6 +29,7 @@ use crate::{
     },
 };
 
+/// Magic number for media catalog files.
 // openssl::sha::sha256(b"Proxmox Backup Media Catalog v1.0")[0..8]
 pub const PROXMOX_BACKUP_MEDIA_CATALOG_MAGIC_1_0: [u8; 8] = [221, 29, 164, 1, 59, 69, 19, 40];
 

src/tape/sgutils2.rs

@@ -1,12 +1,15 @@
-/// Bindings for libsgutils2
+//! Bindings for libsgutils2
-///
+//!
-/// Incomplete, but we currently do not need more.
+//! Incomplete, but we currently do not need more.
+//!
+//! See: `/usr/include/scsi/sg_pt.h`
 
 use std::os::unix::io::AsRawFd;
 
 use anyhow::{bail, Error};
 use libc::{c_char, c_int};
 
+/// Opaque wrapper for sg_pt_base
 #[repr(C)]
 pub struct SgPtBase { _private: [u8; 0] }
 
@@ -79,7 +82,7 @@ extern {
     pub fn get_scsi_pt_result_category(objp: *const SgPtBase) -> c_int;
 }
 
-/// Creates a Box<SgPtBase>
+/// Creates a `Box<SgPtBase>`
 ///
 /// Which get automatically dropped, so you do not need to call
 /// destruct_scsi_pt_obj yourself.
@@ -101,7 +104,9 @@ pub struct SgRaw<'a, F> {
     sense_buffer: [u8; 32],
 }
 
-// alloc page aligned buffer
+/// Allocate a page aligned buffer
+///
+/// SG RAWIO commands needs page aligned transfer buffers.
 pub fn alloc_page_aligned_buffer(buffer_size: usize) -> Result<Box<[u8]> , Error> {
     let page_size = unsafe { libc::sysconf(libc::_SC_PAGESIZE) } as usize;
     let layout = std::alloc::Layout::from_size_align(buffer_size, page_size)?;