# *****************************************************************************
# 
# $Id: README.ss7if,v 0.7.2.1 2000/10/09 02:40:40 brian Exp $
# 
# *****************************************************************************
# 
# Copyright (C) 1997, 1998, 1999, 2000  Brian Bidulock <bidulock@dallas.net>
# 
# All Rights Reserved.
# 
# 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 2 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, write to the Free Software Foundation, Inc., 675 Mass
# Ave, Cambridge, MA 02139, USA.
# 
# Last Modified $Date: 2000/10/09 02:40:40 $ by $Author: brian $
# 
# *****************************************************************************
# 
# $Log: README.ss7if,v $
# Revision 0.7.2.1  2000/10/09 02:40:40  brian
# Pre-release 1.
#
# Revision 0.7  2000/09/27 17:48:53  brian
# Added readme files for this directory.
#
# *****************************************************************************

General Notes:

For example of how to use the facilities of the SS7/LINK ss7 signalling
link interface facility, see acb56.c in drivers/net (or here).  acb56.c is
a complete working example of a serial interface card implementation to
this driver interface for the Sealevel ACB56 card.

You must use the struct device structure from include/linux/netdevice.h in
the kernel sources.  This device structure is shared by IP and SS7.


REGISTRATION AND DEREGISTRATOIN OF SS7 DEVICES

    There are three ways to register a device as an SS7 interface and
    attach a level 2 SS7 link state machine to a device (in order of
    preference):

    1.  Fill out your device structure with all necessary interface service
        routines (as per IP) and set the dev->type to ARPHRD_SS7, and then
        register the device with register_netdevice().  The netdevice
        notifier will invoke the attach automagically via the ss7mtp
        module.

        This is the preferred method because the netdevice notifier is for
        notification of other changes to the SS7/MTP protocol layer.  In
        particular, it has the ability to be extended to provide
        notification of card insertion and removal events for cPCI, and is
        consistent with the approach used for IP network devices.

        The ss7mtp module must be loaded for this approach to work.
    
    2.  Fill out your device structure with all necessary interface service
        routines (as per IP) and call the exported ss7if_attach() routine
        from the ss7link module.

        This is a BSD-like approach and is preferrable for device drivers
        which are attempting to maintain consistency with future BSD
        implementations of OpenSS7.

    3.  Fill out an ss7if_register structure with the interface service
        routines which would normally be in the device structure and call
        ss7if_register() from the ss7link module with a master device and
        the register structure.

        This approach is particularly useful for multichannel devices which
        do no require or maintain a full device structure per channel.

    There are only two ways to detach from an SS7 interface and undo what
    was done during the attach:

    1.  Deregister the device wtih unregister_netdevice() which will
        automagically detach (from the destructor of the device structure
        which was set by the attach operation).

    2.  Call either ss7if_unregister() or ss7if_detach() (which are really
        the same functtion).

    NOTE: devices should be closed with dev_close() before calling
    unregister_netdevice().  dev_close() should not be called on an
    operating signalling link (you'll get lots of error messages, but thed
    device will close and unregister correctly).


RECEIVE INTERRUPT SERVICE ROUTINE INTERFACE

    void ss7if_rx(struct sk_buff *skb);

    When delivering received packets in the driver, the driver should not
    call netif_rx() as it would in the IP case, but, instead, and
    equivocally, should call ss7if_rx() so that the SS7 L2 state machine
    has a crack at the packet.  Failing to do so will result in erroneous
    operation.  ss7if_rx() processes each frame through the L2 state
    machine which is part of the ss7link module before ultimately
    delivering each packet up using the actual netif_rx().

    Please see the acb56.c file in drivers/net for more detail.

    Following is the Rx ISR API to the SS7 LINK state machines.  There are
    four functions which must be called in different circumstances and have
    different behaviors which must be followed in the driver.  To
    summarize, they are:

    ss7if_rx()  Called with an sk_buff when the driver has a valid received
                frame.  A valid received frame is a frame which was
                received without error and is between 3 and dev->mtu in
                length and has a valid length indicator in the frame.  if
                the driver is in octet counting mode, it must stop octet
                counting.
                
                The sk_buff must have dev pointer, protocol, pkt_type and
                priority appropriately set.  That is dev is set to the
                device structure of the receiving device, protocol is set
                to AF_SS7, pkt_type is set to ETH_P_SS7, and priority is
                set to TC_PRIO_BESTEFFORT.

    ss7if_los() Called with the device pointer when the driver loses flag
                synchronization on the line.  The driver must enter octet
                counting mode after sending this indication.

    ss7if_err() Called with the device pointer when the driver detects
                frame-related error such as an abort, residue error,
                framing error, CRC error.  The driver must enter octet
                counting mode after sending this indication.

    ss7if_oct() Called with the device pointer when the driver is in octet
                counting mode.  It must be called every 16 octet times (128
                bit times) when the driver is in octet counting mode.

    ss7if_rpt() Called with the device pointer when the driver receives a
                repeat of the last received FISU or LSSU (while not in
                octet counting mode).  This is used because the driver has
                extremely critical timings while the line is idling FISUs
                or LSSUs.  The state machine doesn't do its own FISU/LSSU
                compression, it must be done in the driver.


