Updated documentation with sequence diagrams and descriptions of the beginning of a tape session.

Checking in PDF as the graphs use packages currently unavailable in SLC5.
Updated cmake/rpm to use the pre-packaged pdf.

Documentation/CMakeLists.txt

@@ -4,5 +4,5 @@ INPUTS ProgrammersManual.tex AdministratorsManual.tex
 IMAGE_DIRS images
 NO_DEFAULT USE_INDEX MANGLE_TARGET_NAMES)
 
-INSTALL(FILES ${CMAKE_BINARY_DIR}/Documentation/TapeServer.pdf
+INSTALL(FILES TapeServer.pdf
 DESTINATION /usr/share/doc/tape-server/)

Documentation/ProgrammersManual.tex

@@ -45,7 +45,18 @@ It will connect to the CAStor disk servers to transfer the data itself, using on
 protocols (current candidates are rfio, xroot and ceph) and it will use the services of the Remote 
 Media Changer daemon (rmcd) to mount and unmount tapes.
 
-\subsection{Collaboration diagrams and sequences}
+\subsubsection{Tape session triggering}
+
+The tape server acts as a server only on one occasion, when it receives a client info request from the 
+VDQM. This call triggers a tape session, recall or migrate. The information received at that point
+is only client system information and drive information (request ID, host, port, DGN, tape drive name and user information (user id, etc...)).
+
+The main thread of the tape server will then just forks (and maybe exec, to be decided (TODO)) a new
+process, which will handle the session and quit.
+
+A new session starts with the tape server connecting with the client (it could be the tape gateway, or one of the command line commands of castor (currently packages in castor-tapebridge-client: readtp, writetp, 
+dumptp). In the case of the tape gateway, it can be either a read or a write session.
+
 The collaboration diagrams of the previous version of the tape server (with all its sub components)
 can be found in dot format
 	\footnote{ \href{http://svn.cern.ch/guest/CASTOR/CASTOR2/trunk/castor/tape/doc/collaboration\_diagrams/}
@@ -53,28 +64,73 @@ can be found in dot format
 	
 The new sequencing of a session start, simplified from the internal component communication is shown here:
 
+\begin{center}
 \begin{sequencediagram}
-	\newthread{gw}{tapegatewayd}
 	\newthread{vm}{vmgrd}
 	\newthread{vd}{vdqmd}
 	\newthread{ts}{tapeserverd(main)}
+	\newinst{tsc}{tapeserverd(child process)}
+	\newthread{gw}{client(gateway or command line)}
 	
 	\begin{call}{gw}{get volume}{vm}{tape VID}
 	\end{call}
-	\begin{call}{gw}{get drive}{vd}{VDQM request ID}
+	\begin{call}{gw}{vdqm request/volume stuff}{vd}{VDQM request ID}
+	\end{call}
+	\begin{call}{vd}{schedule}{vd}{}
+	\end{call}
+	\begin{call}{ts}{unitStatus(UP)}{vd}{}
 	\end{call}
 	\begin{call}{vd}{schedule}{vd}{}
 	\end{call}
-	\begin{call}{vd}{client info}{ts}{}
+	\begin{call}{vd}{VDQM\_CLIENTINFO}{ts}{}
+	\end{call}
+	\begin{call}{ts}{fork}{tsc}{}
+		\begin{call}{tsc}{Volume request}{gw}{}
+		\end{call}
+		\begin{call}{tsc}{Proceed with session}{tsc}{}
+		\end{call}
 	\end{call}
+
 \end{sequencediagram}
+\end{center}
+
+At that point, already two client libraries are in use in the tape server: the tape gateway protocol client library and the vdqm client library, and a simple server, answering only one type or requests:
 
+\begin{itemize}
+\item{}The client library for the tape gateway is implemented using the UML/umbrello based serialisation system. It is contained in the \verb#castor::tape::tapebridge::ClientProxy# class in CAStor.
+\item{}The direct C client API in CAStor's \verb#h/vdqm_api.h#.
+\item{}The VDQM request handler is implemented in \verb#castor::tape::tapebridge::VdqmRequestHandler#.
+\end{itemize}
+
+\subsubsection{Tape session startup}
+
+Upon reception of the session request, the tape server checks that it can continue with the session.
+
+Check with VMGR the volume status and block size. A disabled volume can only be mounted by a TP\_OPER.
+
+In case of a write session, queries pool info to know the owner.
+
+If user is not the owner or ADMIN, refuse the mount.
+
+Then reports are sent:
+\begin{itemize}
+\item{}Reports to VDQM that the drive is assigned. (VDQM\_UNITSTATUS).
+\item{}Requests work to be done from the client to prevent useless mounts (and start caching data 
+in case of migration.
+\item{}Mounts the tape, rewinds and validates the volume label.
+\item{}Reports to VMGR that the volume is mounted (\verb#VMGR_TPMOUNTED#).
+\item{}Reports to the VDQM that the tape is mounted (VDQM\_UNITSTATUS).
+\end{itemize}
+
+\subsubsection{Work loop}
 TODO: VDQM status reporting sequencing
 
 TODO: Mount time checks
 
 TODO: GW protocol
 
+\subsubsection{Release tape}
+
 \subsection{Extra requirements}
 Additional requirements, arising from the current practices of operators are:
 

Documentation/TapeServer.toc

-\contentsline {chapter}{Preface}{4}{chapter*.2}
-\contentsline {chapter}{\numberline {1}Developer's manual}{5}{chapter.1}
-\contentsline {section}{\numberline {1.1}Requirements}{5}{section.1.1}
-\contentsline {subsection}{\numberline {1.1.1}Targeted environment}{5}{subsection.1.1.1}
-\contentsline {subsection}{\numberline {1.1.2}Pre-existing requirements}{5}{subsection.1.1.2}
-\contentsline {subsection}{\numberline {1.1.3}Collaboration diagrams and sequences}{5}{subsection.1.1.3}
-\contentsline {subsection}{\numberline {1.1.4}Extra requirements}{6}{subsection.1.1.4}
-\contentsline {section}{\numberline {1.2}Tape server architecture}{6}{section.1.2}
-\contentsline {section}{\numberline {1.3}Reference documentations}{7}{section.1.3}
-\contentsline {subsection}{\numberline {1.3.1}SCSI specifications}{7}{subsection.1.3.1}
-\contentsline {subsubsection}{\numberline {1.3.1.1}Manufacturer's specificities}{7}{subsubsection.1.3.1.1}
-\contentsline {subsection}{\numberline {1.3.2}SCSI support in Linux}{7}{subsection.1.3.2}
-\contentsline {subsection}{\numberline {1.3.3}Unsorted CAStor docs}{8}{subsection.1.3.3}
-\contentsline {subsection}{\numberline {1.3.4}SCSI tape support in Linux (st driver)}{8}{subsection.1.3.4}
-\contentsline {section}{\numberline {1.4}Tools used during development}{9}{section.1.4}
-\contentsline {subsection}{\numberline {1.4.1}Required tools for build}{9}{subsection.1.4.1}
-\contentsline {subsection}{\numberline {1.4.2}Tools used during development}{9}{subsection.1.4.2}
-\contentsline {subsection}{\numberline {1.4.3}Code coverage using lcov}{9}{subsection.1.4.3}
-\contentsline {section}{\numberline {1.5}Software layout}{10}{section.1.5}
-\contentsline {subsection}{\numberline {1.5.1}SCSI structures, constants and endianness}{10}{subsection.1.5.1}
-\contentsline {subsection}{\numberline {1.5.2}Exceptions hierarchy and error handling strategy}{11}{subsection.1.5.2}
-\contentsline {subsection}{\numberline {1.5.3}Non-fatal warnings strategy}{11}{subsection.1.5.3}
-\contentsline {subsection}{\numberline {1.5.4}The Tape::Drive object}{13}{subsection.1.5.4}
-\contentsline {subsection}{\numberline {1.5.5}The Tape::File class}{14}{subsection.1.5.5}
-\contentsline {subsubsection}{\numberline {1.5.5.1}CAStor file format}{14}{subsubsection.1.5.5.1}
-\contentsline {subsubsection}{\numberline {1.5.5.2}File block management}{19}{subsubsection.1.5.5.2}
-\contentsline {subsubsection}{\numberline {1.5.5.3}Responsibilities of the class}{19}{subsubsection.1.5.5.3}
-\contentsline {subsubsection}{\numberline {1.5.5.4}Checksums}{19}{subsubsection.1.5.5.4}
-\contentsline {subsubsection}{\numberline {1.5.5.5}Tape::File API}{20}{subsubsection.1.5.5.5}
-\contentsline {subsection}{\numberline {1.5.6}Memory chunk manager}{20}{subsection.1.5.6}
-\contentsline {subsection}{\numberline {1.5.7}FIFOs}{20}{subsection.1.5.7}
-\contentsline {subsection}{\numberline {1.5.8}Disk client library}{20}{subsection.1.5.8}
-\contentsline {subsection}{\numberline {1.5.9}VDQM client library}{20}{subsection.1.5.9}
-\contentsline {subsection}{\numberline {1.5.10}VMGR client library}{20}{subsection.1.5.10}
-\contentsline {subsection}{\numberline {1.5.11}Stager/TapeGateway client library}{20}{subsection.1.5.11}
-\contentsline {subsection}{\numberline {1.5.12}Logging system client library}{20}{subsection.1.5.12}
-\contentsline {subsection}{\numberline {1.5.13}Application architecture}{20}{subsection.1.5.13}
-\contentsline {subsubsection}{\numberline {1.5.13.1}Session spawner}{20}{subsubsection.1.5.13.1}
-\contentsline {subsubsection}{\numberline {1.5.13.2}Session process}{20}{subsubsection.1.5.13.2}
-\contentsline {subsubsection}{\numberline {1.5.13.3}Tape read thread}{20}{subsubsection.1.5.13.3}
-\contentsline {subsubsection}{\numberline {1.5.13.4}Tape write thread}{20}{subsubsection.1.5.13.4}
-\contentsline {subsubsection}{\numberline {1.5.13.5}Disk read thread}{20}{subsubsection.1.5.13.5}
-\contentsline {subsubsection}{\numberline {1.5.13.6}Disk write thread}{20}{subsubsection.1.5.13.6}
-\contentsline {chapter}{\numberline {2}Administrator's manual}{21}{chapter.2}
-\contentsline {section}{\numberline {2.1}Pending questions}{21}{section.2.1}

tape-server.spec

@@ -66,7 +66,8 @@ test -e $RPM_BUILD_ROOT && rm -r $RPM_BUILD_ROOT
 mkdir -p build
 cd build
 cmake ../ -DRELEASE=%{release} -DCMAKE_BUILD_TYPE=Debug
-%{__make} %{_smp_mflags} all TapeServer_pdf
+%{__make} %{_smp_mflags} all 
+#TapeServer_pdf
 
 %install
 cd build