1 files changed, 100 insertions, 0 deletions
diff --git a/xpp/astribank_is_starting.8 b/xpp/astribank_is_starting.8
new file mode 100644
index 0000000..55db6f6
--- /dev/null
+++ b/xpp/astribank_is_starting.8
@@ -0,0 +1,100 @@
+.TH "ASTRIBANK_IS_STARTING" "8" "16 August 2009" "" ""
+
+.SH NAME
+astribank_is_starting \- Mark / check is a Xorcom Astribank (xpp) is starting
+.SH SYNOPSIS
+.B astribank_is_starting [-d] [-v] [-t \fItimeout\fB] <-a|-r|-w>
+
+.B astribank_is_starting [-d] [-v]
+
+.B astribank_is_starting -h
+
+.SH DESCRIPTION
+.B astribank_is_starting
+is an internal tool used by various xpp scripts to mark that there may
+be an Astribank device currently initializing, and to check for that mark.
+
+Technically the mark is a SysV semaphore.
+
+.SH OPTIONS
+.B -a
+.RS
+.B Add.
+Set the mark. Should return 0 unless there's an error.
+.RE
+
+.B -r
+.RS
+.B Remove.
+Reset the mark. Should return 0 unless there's an error.
+.RE
+
+.BI -t timeout
+.RS
+.B Timeout.
+Set the timeout value for the \fB-w\fR option. Default is 60 seconds.
+.RE
+
+.B -w
+.RS
+.B Wait.
+Wait for mark to be reset. Should return 0 unless there's an error.
+.RE
+
+Without -a or -r: return 0 if the mark has been set, or a non-zero value
+otherwise.
+
+.B -d
+.RS
+Print debug information to stderr.
+.RE
+
+.B -v
+.RS
+Verbose execution.
+.RE
+
+.B -h
+.RS
+Displays usage message.
+.RE
+
+.SH FILES
+.B /proc/sysvipc/sem
+.RS
+If set, the astribank should appear there with the ID 11211168 (0xAB11A0).
+Naturally the ID (or rather, the usage of a semaphore in the first place)
+is an implementation detail that may change.
+.RE
+
+.SH NOTES
+.B astribank_is_starting
+is used to mark the fact that an Astribank may be currently reenumerating
+(technically: distonnecting and connecting as a new USB device) after
+loading the firmware. Thus the script that loads the firmware 
+(/usr/share/dahdi/xpp_fxloader) uses this utility to set the mark.
+
+The mark is reset by /usr/share/dahdi/waitfor_xpds , which is typically
+run by the DAHDI init script and waits for all Astribanks to finish
+loading.
+
+Q: Why do you use a semaphore?
+
+A: because, unlike the filesystem, it is writable at any given time.
+
+.SH BUGS
+Option ordering matter. The \fB-v\fR and \fB-d\fR options should preceed
+the actions (\fB-a\fR, \fB-r\fR and \fB-w\fR).
+The \fB-t\fItimeout\fR option should preceed the \fB-w\fR option.
+
+.SH SEE ALSO
+semctl(3)
+
+.SH AUTHOR
+This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> .
+Permission is granted to copy, distribute and/or modify this document under
+the terms of the GNU General Public License, Version 2 any 
+later version published by the Free Software Foundation.
+
+On Debian systems, the complete text of the GNU General Public
+License can be found in /usr/share/common-licenses/GPL.