dahdi_span_assignments: matched and unmatched
[dahdi/tools.git] / README
diff --git a/README b/README
index d660f34..04cb386 100644 (file)
--- a/README
+++ b/README
@@ -15,8 +15,9 @@ dahdi-linux before building dahdi-tools.
 Build System
 ~~~~~~~~~~~~
 GCC and friends. Generally you will need to install the package gcc.
-There may be cases where you will need a specific version of gcc to build
-kernel modules.
+
+Autotools (autoconf, automake and libtool) are needed if you clone from
+Git.
 
 
 Extra Libraries
@@ -24,20 +25,25 @@ Extra Libraries
 Some libraries are needed for extra utilities that are provided with
 DAHDI.
 
-- libusb is needed for building fpga_load, needed for firmware loading of
-  the Xorcom Astribank.
+- libusb is needed for building astribank_hexload, needed for firmware
+  loading of the Xorcom Astribank.
 - libnewt is needed to build the optional but useful utility dahdi_tool.
+- libpcap is needed for building dahdi_pcap.
+- pppd is needed to build the dahdi pppd plugin.
 
 
 Installation
 ~~~~~~~~~~~~
 Note: If using `sudo` to build/install, you may need to add /sbin to your PATH.
 ----------------------------------
+# Only if you cloned from git:
+autoreconf -i
+
 ./configure
 make
 make install
-# To install init scripts and config files:
-#make config
+# To install some extra configuration files:
+#make install-config
 ----------------------------------
 
 
@@ -49,15 +55,11 @@ There are some make targets that are provided to build or install just
 parts of DAHDI:
 
 . Build targets:
-  - make: Build DAHDI user-space programs. partial
-    targets of it:
-    * make 'utilname': builds 'utilname' alone (e.g: `make dahdi_diag`)
-    * make utils: Build libtonezone.
-    * make libs: Build libtonezone.
+  - make: Build DAHDI user-space programs and libraries.
+  - make docs: Generate some extra documentation files.
 . Install targets:
-  - make install: Installs user space tools into /usr/sbin/ (TODO - list
-    partial targets)
-  - make config: should be run once to configure 
+  - make install: Install everything
+  - make install-config: install configuration files
 
 
 Installation to a Subtree
@@ -73,8 +75,8 @@ This can be useful for any partial install target from the list above.
 
 Options For ./configure
 ^^^^^^^^^^^^^^^^^^^^^^^
-The configure script executes various tests and based on them generates
-makeopts. You can pass it --with options and variable settings, for
+The configure script executes various tests and the build will depend on
+their result. You can pass it --with options and variable settings, for
 instance:
 
   ./configure --without-ncurses CC="gcc-4.10"
@@ -114,32 +116,55 @@ The configuration file of the dahdi init.d script is
 /etc/dahdi/init.conf . That file is used to override defaults that are 
 set at the beginning of the init.d script.
 
+/etc/dahdi/assigned-spans.conf
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Assigns span number and initial channel number for spans in each device.
+Just like system.conf it may be generated with dahdi_genconf:
+
+  dahdi_span_assignments auto
+  dahdi_genconf
+
+It may also be edited manually to allow reserving span and channel
+numbers for specific devices.
+
+/etc/dahdi/span-types.conf
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Theoretically, this file is similar to assigned-spans.conf. It allows
+setting the type (E1/T1) of a "PRI" span. This cannot be configured
+anywhere else: it needs to be done before the span is assigned as it
+changes the number of channels the span has.
+
+In practice most systems don't mix E1 and T1 and thus this file will
+typically have at most a single wild-card line setting all cards to be
+either E1 or T1.
+
+
 Reference Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~
 Sample system.conf
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 include::system.conf.asciidoc[]
 
 
 Sample init.conf
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
 include::init.conf.asciidoc[]
 
 
 Sample genconf_parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^
 FIXME: still not properly formatted.
 
 include::genconf_parameters.asciidoc[]
 
 
 Sample assigned-spans.conf
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 include::assigned-spans.conf.asciidoc[]
 
 
 Sample span-types.conf
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
 include::span-types.conf.asciidoc[]
 
 
@@ -212,6 +237,131 @@ that is included in the ppp/ subdirectory. To install it:
    CONFIG_HDLC .
 
 
+Initialization
+--------------
+This section documents the start up sequence of the DAHDI modules.
+
+There are generally two options: explicit (using an init script) and
+implicit (run from UDEV hook scripts).
+
+Explicit
+~~~~~~~~
+The dahdi init scripts does the following tasks:
+
+* Loading the module dahdi and any other module listed in
+  /etc/dahdi/modules.
+* For xpp (Astribanks) - some specific initializations. See
+  README.Astribank.
+* Runs link:doc/dahdi_cfg.8.html[dahdi_cfg] after all modules were
+  loaded.
+* A number of other tools may need to be run:
+** link:doc/fxotune.8.html[fxotune]
+** dahdihpec_enable
+
+Only at this point Asterisk (or any other user of DAHDI) can be run.
+
+
+Implicit
+~~~~~~~~
+(Also known as "hot-plug" or "pinned-spans". This requires:
+
+* dahdi >= 2.8.0
+* Setting the module parameter auto_assign_spans of dahdi to 0
+* (Recommended) Asterisk >= 12 - which supports "dahdi create channels".
+
+When a device driver of a DAHDI device finishes initialization, it
+creates a dahdi_device kernel object. A dahdi_device represents a single
+DAHDI device (such as a PCI card) and may have several spans. If the
+value of auto_assign_spans is 1 when dahdi_device is created, spans are
+assigned automatically - each new span gets the first available span
+number and range of channels. However if it is set to 0, spans will not
+get assigned, and user space programs need to assign them. The
+low-level interface for doing so is explained in the section "Span
+Assignment" in the README of DAHDI-Linux.
+
+New Devices
+^^^^^^^^^^^
+When a kernel object is created or destroyed, the kernel sends an event
+to user space. Those events are normally handled by udevd. Configurations
+for udevd ("udev rules") may be placed in /etc/udev/rules.d or
+/lib/udev/rules.d. This package installs rules that instruct udevd to
+run the script `/usr/share/dahdi/dahdi_handle_device` on each new
+device, which runs all the scripts in `/usr/share/dahdi/handle_device.d`.
+Those scripts will:
+
+* If `/etc/dahdi/span-types.conf` exists, apply it to the device. It is
+ used for E1/T1/J1 settings. See
+ <<_sample_span_types_conf,sample span-types.conf>>.
+
+* If `/etc/dahdi/assigned-spans.conf` exists, assign the span according
+ to it (if it is not specified there: don't assign it).
+ used for E1/T1/J1 settings. See
+ <<_sample_assigned_spans_conf,sample assigned-spans.conf>>.
+
+* But if that file does not exist, assign the span to the first
+  available place.
+
+This script mainly uses the commands
+link:doc/dahdi_span_types.8.html[dahdi_span_types] and
+link:doc/dahdi_span_assignments.8.html[dahdi_span_assignments].
+
+DAHDI devices are listed under `/sys/bus/dahdi_devices/devices`.
+
+If you want to disable running this script, add the following line to
+`/etc/dahdi/init.conf`:
+.............................
+DAHDI_UDEV_DISABLE_DEVICES=yes
+.............................
+
+
+New Spans
+^^^^^^^^^
+Once a span is assigned, a kernel object will appear for it. It will be
+listed under its device. As a new kernel object was created, an event is
+sent to udev.
+
+The standard DAHDI udev rules instruct udevd to run the script
+`/usr/share/dahdi/dahdi_span_config` which runs all the scripts in
+`/usr/share/dahdi/span_config.d`. Those script configures the new
+span:
+
+* If system.conf does not exist, generates a temporary configuration
+  for the span using link:doc/dahdi_genconf.8.html[dahdi_genconf
+  system].
+
+* Runs link:doc/dahdi_cfg.8.html[dahdi_cfg] on the new span (using `-S`
+  and -C`).
+
+* Runs `asterisk -rx 'dahdi create channels'` to add the new channels
+  and spans to Asterisk (if they were configured in advance).
+
+If you want to disable running this script, add the following line to
+`/etc/dahdi/init.conf`:
+.............................
+DAHDI_UDEV_DISABLE_SPANS=yes
+.............................
+
+
+New Channels
+^^^^^^^^^^^^
+DAHDI channels have their own representation in the kernel. The standard
+udev rules that dahdi-tools includes for them, however, don't run a
+script for each device. Each DAHDI channel creates a block device file
+at /dev/dahdi/chan/'span'/'rel-chan', where 'span' and 'rel-chan' are
+each three-digit numbers (e.g: 035). 'span' is the span number and
+'rel-chan' is the channel number relative to the span.
+
+The udev rules generate the following extra symlinks under /dev/dahdi:
+
+* /dev/dahdi/'num' - the channel number. As it was originally (but
+  continues beyond 250).
+* /dev/dahdi/devices/'hardware_id'/'rel-span'/'rel-chan' - if the DAHDI
+  device has a hardware ID field, provide listing of the device's span
+  and channels.
+* /dev/dahdi/devices/@'hardware_id'/'rel-span'/'rel-chan' - likewise for
+  the connector field. It has a "@" prefix.
+
+
 include::UPGRADE.txt[]