Skip to content
GitLab
Commit 36b2c127 authored by Eric Cano's avatar Eric Cano
Browse files

Created a pdf documentation, based on the CASTOR documentation template. Used Latex as in CASTOR. 

Imported the castordoc.cls from CASTOR. Fixed left/right page footer mix-up.
Imported package UseLATEX.cmake to allow its compilation.
Started development of a SCSI::Device (incomplete).
Updated location of the Doxygen configuration file.
Added compilation of documentation and Doxygen by default in rpm build.
parent 422c2f08
Expand all Hide whitespace changes
Inline Side-by-side
CMakeLists.txt
View file @ 36b2c127
......@@ -85,9 +85,13 @@ set (CMAKE_CXX_FLAGS “${CMAKE_CXX_FLAGS} -Wall -Werror -pedantic”)
find_package(Doxygen)
if(DOXYGEN_FOUND)
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
add_custom_target(doc
add_custom_target(doxygen
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen" VERBATIM
)
endif(DOXYGEN_FOUND)
\ No newline at end of file
endif(DOXYGEN_FOUND)
INCLUDE(cmake/UseLATEX.cmake)
add_subdirectory(Documentation)
Documentation/CMakeLists.txt 0 → 100644
View file @ 36b2c127
ADD_LATEX_DOCUMENT(
TapeServer.tex
INPUTS ProgrammersManual.tex
IMAGE_DIRS images
NO_DEFAULT MANGLE_TARGET_NAMES)
Documentation/ProgrammersManual.tex 0 → 100644
View file @ 36b2c127
\chapter*{Preface}
The Tape server project is targeted at replacing the CASTOR tape server with a new drop-{}in reimplementation. The reimplementation will replace a legacy implementation that is written in C.
% -------
% Chapter
% -------
\chapter{Developer's manual}
\section{Targeted environment}
CERN SLC5 and SLC6, 64bits. Although it should compile in theory, the 32 bits version is not tested. [ TODO: prevent 32 bits compilation ]
\section{Reference documentations}
The SCSI commands can be found in the SCSI section of hackipedia:
\href{http://hackipedia.org/Hardware/SCSI/}{http://hackipedia.org/Hardware/SCSI/}.
The most significant sections for tape server development are the stream commands
\href{http://hackipedia.org/Hardware/SCSI/Stream%20Commands/SCSI%20Stream%20Commands%20-%203.pdf}{
http://hackipedia.org/Hardware/SCSI/Stream Commands/SCSI Stream Commands - 3.pdf} and the
\href{http://hackipedia.org/Hardware/SCSI/Primary%20Commands/SCSI%20Primary%20Commands%20-%204.pdf}{SCSI primary commands}.
On the Linux side, the main references are the Linux SCSI Generic (sg) HOWTO
\href{http://tldp.org/HOWTO/SCSI-Generic-HOWTO/index.html}{ http://tldp.org/\-HOWTO/\-SCSI-{}Generic-{}HOWTO/\-index.html } , and ... TBC.
http://sg.danny.cz/sg/sg\_io.html
http://sg.danny.cz/sg/index.html
\section{Tools used during development}
\subsection{ Required tools for build}
\begin{itemize}
\item{}GCC/G++ (Basic SLC version)
\item{}CMake (Basic SLC version)
\item{}rpmbuild (Basic SLC version)
\end{itemize}
Google Mock/Google test (GTest is provided in EPEL repository for SLC. GMock requires recompilation (TODO: link to source)
Valgrind (Basic SLC version)
Docbook (Basic SLC version)
Doxygen for code documentation
\subsection{Tools used during development}
\begin{itemize}
\item{}TeamCity for continuous integration
\item{}NetBeans as an IDE, including for remote development
Syntext Serna Free for docbook documents edition
\end{itemize}
\end{document}
Documentation/TapeServer.tex 0 → 100644
View file @ 36b2c127
\documentclass{castordoc}
%\usepackage{url}
% For clickable links and good readability using dvipdf
\usepackage{times}
\usepackage{color}
\usepackage[ps2pdf,colorlinks=true,linkcolor=webred]{hyperref}
\definecolor{webred}{rgb}{0.5,0,0}
\begin{document}
\doctyp{CASTOR Tape Server Documentation}
\dociss{1}
\docrev{0}
\docref{http://www.cern.ch/castor}
\doccre{Wed July 3\textsuperscript{rd}, 2013}
\docmod{\today}
\title{Tape Server's Handbook}
\author{CASTOR development team}
\maketitle
\tableofcontents
\input{ProgrammersManual}
\end{document}
Documentation/castordoc.cls 0 → 100644
View file @ 36b2c127
%
% castordoc.cls
%
% LaTeX style for castor documentation
%
% written by sebastien.ponce@cern.ch, inspired from
% lhcbnote.cls (See http://lhcb-comp.web.cern.ch/lhcb-comp/Support/LateX/lhcbnote.tex)
%
\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{castordoc}[]
\LoadClass[twoside,a4paper]{report}
\RequirePackage{calc}
\RequirePackage{array}
\RequirePackage{a4wide}
\RequirePackage{fancyhdr}
\RequirePackage{graphicx}
\renewcommand\chapter{\if@openright\cleardoublepage\else\clearpage\fi
\thispagestyle{fancy}%
\global\@topnum\z@
\@afterindentfalse
\secdef\@chapter\@schapter}
\def\@docref{\mbox{-}}
\def\@docrev{\mbox{-}}
\def\@dociss{\mbox{-}}
\def\@docmod{\mbox{-}}
\def\@doccre{\mbox{-}}
\def\@doctyp{\mbox{}}
\newcommand{\docref}[1]{\def\@docref{\mbox{#1}}}
\newcommand{\docrev}[1]{\def\@docrev{\mbox{#1}}}
\newcommand{\dociss}[1]{\def\@dociss{\mbox{#1}}}
\newcommand{\docmod}[1]{\def\@docmod{\mbox{#1}}}
\newcommand{\doccre}[1]{\def\@doccre{\mbox{#1}}}
\newcommand{\doctyp}[1]{\def\@doctyp{\mbox{#1}}}
\setlength{\voffset}{-1in}
\setlength{\headheight}{2cm}
\renewcommand{\footrulewidth}{0.4pt}
\addtolength{\textheight}{1cm}
%%
\def\ps@myheadings{%
\let\@oddfoot\@empty\let\@evenfoot\@empty
\def\@evenhead{\thepage\hfil\slshape\leftmark}%
\def\@oddhead{{\slshape\rightmark}\hfil\thepage}%
\let\@mkboth\@gobbletwo
\let\chaptermark\@gobble
\let\sectionmark\@gobble
}
\if@titlepage
\renewcommand\maketitle{\begin{titlepage}%
\let\footnotesize\small
\let\footnoterule\relax
\let \footnote \thanks
\includegraphics{images/cern_logo} \hfill
\includegraphics{images/CASTOR_logo_250}
\null\vfil
\vskip 60\p@
\begin{center}%
{\Huge \@title \par}%
\vskip 3em%
{\large
\lineskip .75em%
\begin{tabular}[t]{c}%
\@author
\end{tabular}\par}%
\vskip 1.5em%
{\large \@date \par}% % Set date in \large size.
\end{center}\par
\@thanks
\vfil\null
{\Large \@doctyp}
\begin{tabular}[b]{ll}
Issue : & \@dociss \\
Revision : & \@docrev \\
Reference : & \@docref \\
Created : & \@doccre \\
Last modified : & \@docmod \\
\end{tabular}
\end{titlepage}%
\setcounter{footnote}{0}%
\global\let\thanks\relax
\global\let\maketitle\relax
\global\let\@thanks\@empty
\global\let\@author\@empty
\global\let\@date\@empty
\global\let\@title\@empty
\global\let\title\relax
\global\let\author\relax
\global\let\date\relax
\global\let\and\relax}
\else
\renewcommand\maketitle{\par
\begingroup
\renewcommand\thefootnote{\@fnsymbol\c@footnote}%
\def\@makefnmark{\rlap{\@textsuperscript{\normalfont\@thefnmark}}}%
\long\def\@makefntext##1{\parindent 1em\noindent
\hb@xtt@1.8em{%
\hss\@textsuperscript{\normalfont\@thefnmark}}##1}%
\if@twocolumn
\ifnum \col@number=\@ne
\@maketitle
\else
\twocolumn[\@maketitle]%
\fi
\else
\newpage
\global\@topnum\z@ % Prevents figures from going at top of page.
\@maketitle
\fi
\thispagestyle{plain}\@thanks
\endgroup
\setcounter{footnote}{0}%
\global\let\thanks\relax
\global\let\maketitle\relax
\global\let\@maketitle\relax
\global\let\@thanks\@empty
\global\let\@author\@empty
\global\let\@date\@empty
\global\let\@title\@empty
\global\let\title\relax
\global\let\author\relax
\global\let\date\relax
\global\let\and\relax}
\def\@maketitle{%
\newpage
\null
\vskip 2em%
\begin{center}%
\let \footnote \thanks
{\HUGE \@title \par}%
\vskip 1.5em%
{\large
\lineskip .5em%
\begin{tabular}[t]{c}%
\@author
\end{tabular}\par}%
\vskip 1em%
{\large \@date}%
\end{center}%
\par
\vskip 1.5em}
\fi
\pagestyle{fancy}
\addtolength{\headwidth}{\marginparsep}
\addtolength{\headwidth}{\marginparwidth}
\newcommand{\clearemptydoublepage}{\newpage{\pagestyle{empty}\cleardoublepage}}
\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
\renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}}
\rhead[\fancyplain{}{\bfseries\scriptsize\mbox{%
\begin{tabular}{@{}l@{}}
Title: \@title \@author\\%
\@doctyp\\%
Issue: \@dociss\\%
\leftmark\end{tabular}}}]
{\fancyplain{}{\bfseries\scriptsize\mbox{%
\begin{tabular}{@{}l@{}}
\setlength{\tabcolsep}{0pt}%
\@title\\%
\@doctyp\\%
Issue: \@dociss\\%
\leftmark\end{tabular}}}}
\lhead[\fancyplain{}{\bfseries\scriptsize\mbox{%
\begin{tabular}{@{}lr@{}}%
Reference: & \@docref\\%
Revision: & \@docrev\\%
Last modified: & \@docmod\\
&\end{tabular}}}]
{\fancyplain{}{\bfseries\scriptsize\mbox{%
\begin{tabular}{@{}lr@{}}%
Reference: & \@docref\\%
Revision: & \@docrev\\%
Last modified: & \@docmod\\
&\end{tabular}}}}
\lfoot[\fancyplain{}{\bfseries\scriptsize page \thepage}]{}
\rfoot[]{\fancyplain{}{\bfseries\scriptsize page \thepage}}
\cfoot{}
\newenvironment{CompactList}
{\begin{list}{}{
\setlength{\leftmargin}{0.5cm}
\setlength{\itemsep}{0pt}
\setlength{\parsep}{0pt}
\setlength{\topsep}{0pt}
\renewcommand{\makelabel}{}}}
{\end{list}}
\newenvironment{CompactItemize}
{
\begin{itemize}
\setlength{\itemsep}{-3pt}
\setlength{\parsep}{0pt}
\setlength{\topsep}{0pt}
\setlength{\partopsep}{0pt}
}
{\end{itemize}}
\newcommand{\PBS}[1]{\let\temp=\\#1\let\\=\temp}
\newlength{\tmplength}
\newenvironment{TabularC}[1]
{
\setlength{\tmplength}
{\linewidth/(#1)-\tabcolsep*2-\arrayrulewidth*(#1+1)/(#1)}
\par\begin{tabular*}{\linewidth}
{*{#1}{|>{\PBS\raggedright\hspace{0pt}}p{\the\tmplength}}|}
}
{\end{tabular*}\par}
\newcommand{\entrylabel}[1]{
{\parbox[b]{\labelwidth-4pt}{\makebox[0pt][l]{\textbf{#1}}\\}}}
\newenvironment{Desc}
{\begin{list}{}
{
\settowidth{\labelwidth}{40pt}
\setlength{\leftmargin}{\labelwidth}
\setlength{\parsep}{0pt}
\setlength{\itemsep}{-4pt}
\renewcommand{\makelabel}{\entrylabel}
}
}
{\end{list}}
\newenvironment{Indent}
{\begin{list}{}{\setlength{\leftmargin}{0.5cm}}
\item[]\ignorespaces}
{\unskip\end{list}}
\setlength{\parindent}{0cm}
\setlength{\parskip}{0.2cm}
\addtocounter{secnumdepth}{2}
\sloppy
Documentation/images/CASTOR_logo_250.eps 0 → 100644
View file @ 36b2c127
This diff is collapsed.
Documentation/images/cern_logo.eps 0 → 100644
View file @ 36b2c127
This diff is collapsed.
Doxyfile.in
View file @ 36b2c127
......@@ -5,7 +5,8 @@ PROJECT_NAME = "@CMAKE_PROJECT_NAME@"
PROJECT_NUMBER = "@VERSION_MAJOR@.@VERSION_MINOR@.@VERSION_PATCH@-@VERSION_TWEAK@"
OUTPUT_DIRECTORY = dox
CREATE_SUBDIRS = NO
INPUT = @CMAKE_SOURCE_DIR@/disk_transfer @CMAKE_SOURCE_DIR@/main @CMAKE_SOURCE_DIR@/bandwidth_simulation
INPUT = @CMAKE_SOURCE_DIR@/Drive @CMAKE_SOURCE_DIR@/Exception @CMAKE_SOURCE_DIR@/SCSI \
@CMAKE_SOURCE_DIR@/System @CMAKE_SOURCE_DIR@/test @CMAKE_SOURCE_DIR@/Utils
CLASS_GRAPH = YES
HAVE_DOT = YES
......
Drive/Drive.hh
View file @ 36b2c127
......@@ -52,6 +52,8 @@ namespace Tape {
/* Read drive status */
if (-1 == m_sysWrapper.ioctl(m_tapeFD, MTIOCGET, &m_mtInfo))
throw Tape::Exceptions::Errnum(std::string("Could not read drive status: "+ m_SCSIInfo.st_dev));
/* Read Generic SCSI information (INQUIRY) */
}
virtual ~Drive() {
if(-1 != m_tapeFD)
......
Drive/DriveTest.cc
View file @ 36b2c127
......@@ -31,6 +31,8 @@ using ::testing::AtLeast;
using ::testing::Return;
using ::testing::_;
namespace UnitTests {
TEST(TapeDrive, OpensCorrectly) {
/* Prepare the test harness */
Tape::System::mockWrapper sysWrapper;
......@@ -59,3 +61,5 @@ TEST(TapeDrive, OpensCorrectly) {
}
}
}
}
SCSI/Constants.hh 0 → 100644
View file @ 36b2c127
// ----------------------------------------------------------------------
// File: SCSI/Constants.hh
// Author: Eric Cano - CERN
// ----------------------------------------------------------------------
/************************************************************************
* Tape Server *
* Copyright (C) 2013 CERN/Switzerland *
* *
* This program is free software: you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation, either version 3 of the License, or *
* (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* You should have received a copy of the GNU General Public License *
* along with this program. If not, see <http://www.gnu.org/licenses/>.*
************************************************************************/
namespace SCSI {
/* Extracted from linux kernel's include/scsi/scsi.h. System-level include
is less complete */
class Types {
public:
enum {
disk = 0x00,
tape = 0x01,
printer = 0x02,
processor = 0x03, /* HP scanners use this */
worm = 0x04, /* Treated as ROM by our system */
rom = 0x05,
scanner = 0x06,
mod = 0x07, /* Magneto-optical disk -
* - treated as TYPE_DISK */
mediumChanger = 0x08,
comm = 0x09, /* Communications device */
raid = 0x0c,
enclosure = 0x0d, /* Enclosure Services Device */
rbc = 0x0e,
noLun = 0x7f
};
};
class Commands {
public:
enum {
/*
* SCSI opcodes, taken from linux kernel sources
* Linux kernel's is more complete than system's
* includes.
*/
TEST_UNIT_READY = 0x00,
REZERO_UNIT = 0x01,
REQUEST_SENSE = 0x03,
FORMAT_UNIT = 0x04,
READ_BLOCK_LIMITS = 0x05,
REASSIGN_BLOCKS = 0x07,
INITIALIZE_ELEMENT_STATUS = 0x07,
READ_6 = 0x08,
WRITE_6 = 0x0a,
SEEK_6 = 0x0b,
READ_REVERSE = 0x0f,
WRITE_FILEMARKS = 0x10,
SPACE = 0x11,
INQUIRY = 0x12,
RECOVER_BUFFERED_DATA = 0x14,
MODE_SELECT = 0x15,
RESERVE = 0x16,
RELEASE = 0x17,
COPY = 0x18,
ERASE = 0x19,
MODE_SENSE = 0x1a,
START_STOP = 0x1b,
RECEIVE_DIAGNOSTIC = 0x1c,
SEND_DIAGNOSTIC = 0x1d,
ALLOW_MEDIUM_REMOVAL = 0x1e,
READ_FORMAT_CAPACITIES = 0x23,
SET_WINDOW = 0x24,
READ_CAPACITY = 0x25,
READ_10 = 0x28,
WRITE_10 = 0x2a,
SEEK_10 = 0x2b,
POSITION_TO_ELEMENT = 0x2b,
WRITE_VERIFY = 0x2e,
VERIFY = 0x2f,
SEARCH_HIGH = 0x30,
SEARCH_EQUAL = 0x31,
SEARCH_LOW = 0x32,
SET_LIMITS = 0x33,
PRE_FETCH = 0x34,
READ_POSITION = 0x34,
SYNCHRONIZE_CACHE = 0x35,
LOCK_UNLOCK_CACHE = 0x36,
READ_DEFECT_DATA = 0x37,
MEDIUM_SCAN = 0x38,
COMPARE = 0x39,
COPY_VERIFY = 0x3a,
WRITE_BUFFER = 0x3b,
READ_BUFFER = 0x3c,
UPDATE_BLOCK = 0x3d,
READ_LONG = 0x3e,
WRITE_LONG = 0x3f,
CHANGE_DEFINITION = 0x40,
WRITE_SAME = 0x41,
UNMAP = 0x42,
READ_TOC = 0x43,
READ_HEADER = 0x44,
GET_EVENT_STATUS_NOTIFICATION = 0x4a,
LOG_SELECT = 0x4c,
LOG_SENSE = 0x4d,
XDWRITEREAD_10 = 0x53,
MODE_SELECT_10 = 0x55,
RESERVE_10 = 0x56,
RELEASE_10 = 0x57,
MODE_SENSE_10 = 0x5a,
PERSISTENT_RESERVE_IN = 0x5e,
PERSISTENT_RESERVE_OUT = 0x5f,
VARIABLE_LENGTH_CMD = 0x7f,
REPORT_LUNS = 0xa0,
SECURITY_PROTOCOL_IN = 0xa2,
MAINTENANCE_IN = 0xa3,
MAINTENANCE_OUT = 0xa4,
MOVE_MEDIUM = 0xa5,
EXCHANGE_MEDIUM = 0xa6,
READ_12 = 0xa8,
WRITE_12 = 0xaa,
READ_MEDIA_SERIAL_NUMBER = 0xab,
WRITE_VERIFY_12 = 0xae,
VERIFY_12 = 0xaf,
SEARCH_HIGH_12 = 0xb0,
SEARCH_EQUAL_12 = 0xb1,
SEARCH_LOW_12 = 0xb2,
SECURITY_PROTOCOL_OUT = 0xb5,
READ_ELEMENT_STATUS = 0xb8,
SEND_VOLUME_TAG = 0xb6,
WRITE_LONG_2 = 0xea,
EXTENDED_COPY = 0x83,
RECEIVE_COPY_RESULTS = 0x84,
ACCESS_CONTROL_IN = 0x86,
ACCESS_CONTROL_OUT = 0x87,
READ_16 = 0x88,
WRITE_16 = 0x8a,
READ_ATTRIBUTE = 0x8c,
WRITE_ATTRIBUTE = 0x8d,
VERIFY_16 = 0x8f,
SYNCHRONIZE_CACHE_16 = 0x91,
WRITE_SAME_16 = 0x93,
SERVICE_ACTION_IN = 0x9e
};
}; // class commands
class OtherConstants {
public:
enum {
/* values for service action in */
SAI_READ_CAPACITY_16 = 0x10,
SAI_GET_LBA_STATUS = 0x12,
/* values for VARIABLE_LENGTH_CMD service action codes
* see spc4r17 Section D.3.5, table D.7 and D.8 */
VLC_SA_RECEIVE_CREDENTIAL = 0x1800,
/* values for maintenance in */
MI_REPORT_IDENTIFYING_INFORMATION = 0x05,
MI_REPORT_TARGET_PGS = 0x0a,
MI_REPORT_ALIASES = 0x0b,
MI_REPORT_SUPPORTED_OPERATION_CODES = 0x0c,
MI_REPORT_SUPPORTED_TASK_MANAGEMENT_FUNCTIONS = 0x0d,
MI_REPORT_PRIORITY = 0x0e,
MI_REPORT_TIMESTAMP = 0x0f,
MI_MANAGEMENT_PROTOCOL_IN = 0x10,
/* values for maintenance out */
MO_SET_IDENTIFYING_INFORMATION = 0x06,
MO_SET_TARGET_PGS = 0x0a,
MO_CHANGE_ALIASES = 0x0b,
MO_SET_PRIORITY = 0x0e,
MO_SET_TIMESTAMP = 0x0f,
MO_MANAGEMENT_PROTOCOL_OUT = 0x10,
/* values for variable length command */
XDREAD_32 = 0x03,
XDWRITE_32 = 0x04,
XPWRITE_32 = 0x06,
XDWRITEREAD_32 = 0x07,
READ_32 = 0x09,
VERIFY_32 = 0x0a,
WRITE_32 = 0x0b,
WRITE_SAME_32 = 0x0d,
/* Values for T10/04-262r7 */
ATA_16 = 0x85, /* 16-byte pass-thru */
ATA_12 = 0xa1 /* 12-byte pass-thru */
};
}; // class OtherConstans
}; // namespace SCSI
SCSI/Device.cc
View file @ 36b2c127
......@@ -20,3 +20,8 @@
* You should have received a copy of the GNU General Public License *
* along with this program. If not, see <http://www.gnu.org/licenses/>.*
************************************************************************/
#include <cstdlib>
#include <scsi/sg.h>
SCSI/Device.hh
View file @ 36b2c127
......@@ -30,33 +30,9 @@
#include "../System/Wrapper.hh"
#include "../Exception/Exception.hh"
#include "../Utils/Regex.hh"
#include "Constants.hh"
namespace SCSI {
/* Extracted from linux kernel's include/scsi/scsi.h. System-level include
is less complete */
class Types {
public:
enum {
disk = 0x00,
tape = 0x01,
printer = 0x02,
processor = 0x03, /* HP scanners use this */
worm = 0x04, /* Treated as ROM by our system */
rom = 0x05,
scanner = 0x06,
mod = 0x07, /* Magneto-optical disk -
* - treated as TYPE_DISK */