add Native ATM Protocol manual.

1 files changed, 116 insertions, 0 deletions

diff --git a/share/man/man4/natm.4 b/share/man/man4/natm.4
new file mode 100644
index 0000000..91cd67a
--- /dev/null
+++ b/share/man/man4/natm.4
@@ -0,0 +1,116 @@
+.Dd December 29, 1997
+.Dt NATM 4
+.Os BSD
+.Sh NAME
+.Nm natm
+.Nd Native Mode ATM Protocol Layer
+.Sh DESCRIPTION
+The BSD ATM software comes with a 
+.Em native mode ATM protocol layer 
+which provides socket level access to AAL0 and AAL5 virtual circuits.
+To enable this protocol layer, add 
+.Dl options NATM
+to your kernel configuration file and re-make the kernel (don't forget
+to do 
+.Dq make clean
+).
+.Sh NATM API
+The NATM layer uses a 
+.Dv struct sockaddr_natm
+to specify a virtual circuit:
+.Bd -literal -offset indent
+struct sockaddr_natm {
+  u_int8_t      snatm_len;              /* length */
+  u_int8_t      snatm_family;           /* AF_NATM */
+  char          snatm_if[IFNAMSIZ];     /* interface name */
+  u_int16_t     snatm_vci;              /* vci */
+  u_int8_t      snatm_vpi;              /* vpi */
+};
+.Ed
+.Pp
+To create an AAL5 connection to a virtual circuit with VPI 0, VCI 201
+one would use the following:
+.Bd -literal -offset indent
+  struct sockaddr_natm snatm;
+  int s, r;
+  s = socket(AF_NATM, SOCK_STREAM, PROTO_NATMAAL5);
+                       /* note: PROTO_NATMAAL0 is AAL0 */
+  if (s < 0) { perror("socket"); exit(1); }
+  bzero(&snatm, sieof(snatm));
+  snatm.snatm_len = sizeof(snatm);
+  snatm.snatm_family = AF_NATM;
+  sprintf(snatm.snatm_if, "en0");
+  snatm.snatm_vci = 201;
+  snatm.snatm_vpi = 0;
+  r = connect(s, (struct sockaddr *)&snatm, sizeof(snatm));
+  if (r < 0) { perror("connect"); exit(1); }
+  /* s now connected to ATM! */
+.Ed
+.Pp
+The 
+.Fn socket
+call simply creates an unconnected NATM socket.  The
+.Fn connect
+call associates an unconnected NATM socket with a
+virtual circuit and tells the driver to enable that virtual circuit
+for receiving data.  After the 
+.Fn connect
+call one can 
+.Fn read
+or 
+.Fn write
+to the socket to perform ATM I/O.
+.Sh Internal NATM operation
+Internally, the NATM protocol layer keeps a list of all active virtual
+circuits on the system in 
+.Dv natm_pcbs .    
+This includes circuits currently being used for IP to prevent NATM and
+IP from clashing over virtual circuit usage.
+.Pp
+When a virtual circuit is enabled for receiving data, the NATM
+protocol layer passes the address of the protocol control block down
+to the driver as a receive 
+.Dq handle .
+When inbound data arrives, the driver passes the data back with the
+appropriate receive handle.   The NATM layer uses this to avoid the
+overhead of a protocol control block lookup.   This allows us to take
+advantage of the fact that ATM has already demultiplexed the data for
+us.
+.Sh Other NATM issues
+We are currently involved with a video server project and are using
+this driver as part of it.  We have a device we build called an MMX.
+You can connect a video camera to an MMX and have it send you a stream
+of of AAL0 cells with the video output in it.  Of course this stream
+is pretty rapid (in fact, it is massive!), and the normal AAL0
+handling of the driver is unable to handle it (you end up with a cell
+per small mbuf trying to make it to the application ... it turns out
+the socket layer can't keep up with that sort of data stream).  To
+solve this problem we have implemented a 
+.Dq raw
+mode which batches unprocessed AAL0 info from the card into larger
+data chunks blocks.  We can save this data to disk in real-time
+without the socket layer freaking out.    Unfortunately, the data has
+RBD (receive buffer descriptors) and cells headers in it, and this has
+to be filtered out after capture.    
+To enable 
+.Dq raw
+mode one does the following ioctl:
+.Bd -literal -offset indent
+  int size = 4000; /* bytes */
+  ret = ioctl(s, SIOCRAWATM, (caddr_t)&size);
+.Ed
+.Pp
+This tells the driver to batch AAL0 data into 4000 bytes chunks,
+rather than the usual 48 bytes chunks.     Admittedly this is somewhat
+gross, but our current application requires it.    In the future we
+hope that video sources send data in nice large AAL5 frames.
+.Sh CAVEAT
+The NATM protocol support is subject to change as
+the ATM protocols develop.  Users should not depend
+on details of the current implementation, but rather
+the services exported.
+.Sh SEE ALSO
+.Xr en 4
+.Sh AUTHORS
+Chuck Cranor of Washington University implemented the NATM protocol layer
+along with the EN ATM driver in 1996 for NetBSD.