xpp: A man page for astribank_is_starting

xpp rev: 7321


git-svn-id: http://svn.asterisk.org/svn/dahdi/tools/trunk@7014 a0bf4364-ded3-4de4-8d8a-66a801d63aff

1 files changed, 78 insertions, 0 deletions

diff --git a/xpp/astribank_is_starting.8 b/xpp/astribank_is_starting.8
new file mode 100644
index 0000000..205e498
--- /dev/null
+++ b/xpp/astribank_is_starting.8
@@ -0,0 +1,78 @@
+.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] <-a|-r>
+
+.B astribank_is_starting [-d]
+
+.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
+
+Without -a or -r: return 0 if the mark has been set, or a non-zero value
+otherwise.
+
+.B -d
+.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 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.