From edda5039d4ba31c64d0610f6d4b6bc473c17f92f Mon Sep 17 00:00:00 2001
From: Dietmar Maurer <dietmar@proxmox.com>
Date: Thu, 21 Jan 2021 13:19:07 +0100
Subject: [PATCH] tape: improve code docs

---
 src/tape/drive/linux_tape.rs        |  8 ++++++++
 src/tape/drive/mam.rs               |  1 +
 src/tape/drive/mod.rs               |  1 +
 src/tape/drive/volume_statistics.rs |  2 ++
 src/tape/file_formats.rs            |  2 ++
 src/tape/media_catalog.rs           |  1 +
 src/tape/sgutils2.rs                | 15 ++++++++++-----
 7 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/src/tape/drive/linux_tape.rs b/src/tape/drive/linux_tape.rs
index cc5492c6..440edba3 100644
--- a/src/tape/drive/linux_tape.rs
+++ b/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>,
 }
 
diff --git a/src/tape/drive/mam.rs b/src/tape/drive/mam.rs
index 7aaa62b8..5af4297e 100644
--- a/src/tape/drive/mam.rs
+++ b/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)?;
diff --git a/src/tape/drive/mod.rs b/src/tape/drive/mod.rs
index e891e6bf..8f6f11da 100644
--- a/src/tape/drive/mod.rs
+++ b/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,
diff --git a/src/tape/drive/volume_statistics.rs b/src/tape/drive/volume_statistics.rs
index a6a8a26c..76445fb5 100644
--- a/src/tape/drive/volume_statistics.rs
+++ b/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,
diff --git a/src/tape/file_formats.rs b/src/tape/file_formats.rs
index 4391ebca..006ccb8b 100644
--- a/src/tape/file_formats.rs
+++ b/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};
diff --git a/src/tape/media_catalog.rs b/src/tape/media_catalog.rs
index d9cdf0ae..223e029a 100644
--- a/src/tape/media_catalog.rs
+++ b/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];
 
diff --git a/src/tape/sgutils2.rs b/src/tape/sgutils2.rs
index 65deed70..1d4bd3f7 100644
--- a/src/tape/sgutils2.rs
+++ b/src/tape/sgutils2.rs
@@ -1,12 +1,15 @@
-/// Bindings for libsgutils2
-///
-/// Incomplete, but we currently do not need more.
+//! Bindings for libsgutils2
+//!
+//! 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)?;