Lines Matching +full:ascii +full:. +full:d
1 .\" Copyright (c) 1996-1999 Whistle Communications, Inc.
2 .\" All rights reserved.
3 .\"
4 .\" Subject to the following obligations and disclaimer of warranty, use and
5 .\" redistribution of this software, in source or object code forms, with or
6 .\" without modifications are expressly permitted by Whistle Communications;
7 .\" provided, however, that:
8 .\" 1. Any and all reproductions of the source or object code must include the
9 .\" copyright notice above and the following disclaimer of warranties; and
10 .\" 2. No rights are granted, in any manner or form, to use Whistle
11 .\" Communications, Inc. trademarks, including the mark "WHISTLE
12 .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as
13 .\" such appears in the above copyright notice or in the software.
14 .\"
15 .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
16 .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
17 .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
18 .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
20 .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
21 .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
22 .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
23 .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
24 .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
25 .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
26 .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
27 .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30 .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
31 .\" OF SUCH DAMAGE.
32 .\"
33 .\" Authors: Julian Elischer <julian@FreeBSD.org>
34 .\" Archie Cobbs <archie@FreeBSD.org>
35 .\"
36 .\" $FreeBSD: src/share/man/man4/netgraph.4,v 1.39.2.1 2001/12/21 09:00:50 ru Exp $
37 .\" $Whistle: netgraph.4,v 1.7 1999/01/28 23:54:52 julian Exp $
38 .\"
49 of kernel objects which perform various networking functions.
52 can be arranged into arbitrarily complicated graphs.
55 which are used to connect two nodes together, forming the edges in the graph.
56 Nodes communicate along the edges to process data, implement protocols, etc.
61 infrastructure.
78 .Em node .
80 to interact with other nodes in a well defined manner.
84 which is a static property of the node determined at node creation time.
86 .Tn ASCII
87 type name.
89 to other nodes.
92 of their respective class.
95 (e.g., the ability to have an
96 .Tn ASCII
97 name).
100 .Tn ASCII
102 used to refer to the node.
104 .Dq .\&
106 .Dq \&:
109 characters (including NUL byte).
113 which is expressed as a 32-bit hex value.
115 .Tn ASCII
116 name assigned to it.
120 one from each node.
121 Data flows bidirectionally between nodes along connected pairs of hooks.
123 and may assign whatever meaning it wants to a hook.
130 .Tn ASCII
132 on that node (other hooks on other nodes may have the same name).
134 .Dq .\&
136 .Dq \&:
140 characters (including NUL byte).
142 A hook is always connected to another hook.
144 and breaking an edge by removing either hook destroys both hooks.
147 A node may decide to assign special meaning to some hooks.
151 the node to start sending debugging information to that hook.
154 control messages.
156 in the graph, one edge at a time.
159 flag set.
160 Each node decides how to handle data coming in on its hooks.
163 directly to some arbitrary other node.
166 for efficiency.
169 .Tn ASCII
174 generic control messages below).
175 Nodes are not required to support these conversions.
177 There are two ways to address a control message.
183 addressing).
185 .Tn ASCII
188 for the message (absolute addressing).
190 by specifying an absolute start node and a sequence of hooks.
193 in the reverse direction.
197 that is suitable for addressing a reply.
201 indicating the type of the message, i.e. how to interpret it.
203 that it understands.
205 implement more than one type of message.
209 operations are functional.
211 calls rather than by using queues and mailboxes.
215 data delivery function.
218 method.
226 message before the original delivery function call returns.
229 sections.
231 from a different priority level.
233 move message delivery inside a critical section.
234 Note that messages are always received from inside a critical section.
236 It's possible for an infinite loop to occur if the graph contains cycles.
239 So far, these issues have not proven problematical in practice.
244 subsystem, such as device hardware, kernel protocol stacks, etc.
248 consistent communication framework.
256 .Dv PF_NETGRAPH .
258 .Nm .
261 cooperating user process.
264 a node interface to the hardware.
272 The constructor for the type is called.
276 and then allocate any special resources it needs.
278 the device attach routine.
280 .Tn ASCII
282 device name is assigned here as well.
286 used to describe this hook.
288 or may reject the connection, based on the name of the hook.
293 the connection.
294 Tear-down is automatic.
296 The node is notified of a broken connection.
299 event while for another it may affect a total shutdown for the node.
303 at this time are taken.
304 The method must call the generic (i.e. superclass)
305 node destructor to get rid of the generic components of the node.
309 but doesn't remove it, in which case the generic destructor is not called.
315 An mbuf chain is passed to the node.
317 and can use this information in its processing decision.
321 (or kernel module) which will then be responsible for freeing it.
325 (e.g. priority information).
328 if there is no additional information.
334 .Dv M_NETGRAPH .
337 the meta-data.
338 If the mbuf chain is freed the meta-data must be freed at the same time.
341 pointer must be substituted.
345 NETISR system (see below).
350 at a higher priority than data packets.
351 This is required for conformance with Frame Relay standards.
354 .Em Receive data message.
356 the node after having been queued in the NETISR system.
361 it will not be queued again.
363 This method is called when a control message is addressed to the node.
365 that originated the message so a reply message can be sent anytime later.
368 is more common in practice.
370 to point to the reply.
375 and containing the synchronous response.
379 the control message buffer.
383 .Dv M_NETGRAPH .
387 free'd of all references are automatically freed, and this behaviour
391 writer to use.
396 addressing any single node in the graph.
399 order to address it so as to send it a generic message type.
400 Node and hook names should be chosen so as to make addresses meaningful.
402 Addresses are either absolute or relative.
404 followed by a sequence of hook names separated by periods.
406 at the named node and following the specified sequence of hooks.
408 starting hook traversal at the local node.
410 There are a couple of special possibilities for the node name.
412 .Dq .\&
414 .Dq \&.: )
415 always refers to the local node.
417 by enclosing the hex representation of the ID number within square brackets.
421 .:
423 .:hook1
424 foo:hook1.hook2
438 [ D ]
443 .Em "Frame1:uplink.dlci16" .
445 .Em "Frame1:uplink.dlci20"
446 could reliably be used to reach node D, and node A could refer
448 .Em ".:uplink" ,
450 .Em "uplink" .
452 .Em "data" .
454 .Em "mux.data"
455 could be used by both nodes C and D to address a message to node A.
458 .Em control messages .
460 hook, with each node making the next routing decision.
464 and then forwards the unwrapped frame to either C or D.
492 subsystem.
496 .Dv "node->refs" .
499 a node the list of all active hooks.
503 /** How to convert a control message from binary <-> ASCII */
539 /** How to convert control messages binary <-> ASCII */
569 and the command.
573 Indicates the version of netgraph itself.
575 .Dv NG_VERSION .
578 .Dv data .
580 Indicates whether this is a command or a response control message.
585 corresponding command message; the reply always has the same token.
587 The corresponding node type's unique 32-bit value.
590 .Er EINVAL .
593 argument format, and cookie for its own messages.
599 be changed.
602 (i.e. the output of
603 .Dv "date -u +'%s'" ) .
610 a corresponding set of generic messages which all nodes understand.
611 The handling of these messages is automatic.
613 The identifier for the message command.
615 and is defined in the same header file as the typecookie.
619 (for debugging purposes only).
623 of the header files and thus recognize more than one type cookie.
624 .Sh Control Message ASCII Form
625 Control messages are in binary format for efficiency.
629 .Tn ASCII
630 form.
632 .Tn ASCII
640 .Tn ASCII
643 header field.
648 .Tn ASCII
649 string version of the message arguments.
653 arbitrary C data type.
656 .Tn ASCII
661 Integer types are represented by base 8, 10, or 16 numbers.
664 C language backslash escapes.
666 IP addresses have the obvious form.
669 consecutively starting at index zero.
670 An element may have an optional index and equals sign preceding it.
672 implicitly the previous element's index plus one.
676 .Dq fieldname=value .
680 may be omitted.
682 for string types, the empty string.
684 Array elements and structure fields may be specified in any order.
688 the necessary routines to parse and unparse.
689 .Tn ASCII
692 that node type.
695 for any node, as they are supported directly by the framework itself.
698 along with the basic layout of messages and other similar information.
701 Connect to another node, using the supplied hook names on either end.
704 supplied hook names.
706 The target node should disconnect from all its neighbours and shut down.
708 might not disappear from the node namespace, but only reset themselves.
709 The node must disconnect all of its hooks.
711 cascading shutdown of the entire connected graph.
713 Assign a name to a node.
717 method.
718 Such nodes can only be addressed relatively or by their ID number.
720 Ask the node to break a hook connection to one of its neighbours.
723 method invoked.
724 Either node may elect to totally shut down as a result.
726 Asks the target node to describe itself.
728 the node ID and the number of hooks attached.
729 The ID is an internal number unique to that node.
735 the node at the far end of that link.
739 where each entry of the array describes a named node.
740 All named nodes will be described.
744 except that all nodes are listed regardless of whether they have a name or not.
746 This returns a list of all currently installed netgraph types.
748 The node may return a text formatted status message.
749 The status information is determined entirely by the node type.
752 elect to not support this message.
755 bytes in length (presently 1024).
757 status information in human readable form.
760 .Tn ASCII
761 form.
765 message itself.
767 .Tn ASCII
768 form.
772 is often the same node that would actually receive that message.
775 .Dv NGM_BINARY2ASCII .
777 .Tn ASCII
787 the arguments in the arguments field.
789 contains the binary version of the control message.
795 aspect of that data.
803 data.
805 it should ignore that option.
808 or special processing requirements.
809 It might also mark a packet for debug status, etc.
810 The use of meta-data is still experimental.
816 .Xr kldload 8 .
821 in your kernel configuration file.
834 .Xr kldload 8 .
843 .Pa ng_type.ko .
846 may want to export each instance of the device as a netgraph node.
853 structure.
857 macro automates this process by using a linker set.
859 Several node types currently exist.
864 .Dv PF_NETGRAPH .
870 .Dv SOCK_DGRAM .
871 Typically one of each is associated with a socket node.
872 When both sockets have closed, the node will shut down.
877 socket is used for sending and receiving control messages.
884 socket address.
888 for data, Useful for testing.
889 Always accepts new hooks.
892 hook from which it arrived.
893 Returns any non generic messages as their own response.
894 Useful for testing.
895 Always accepts new hooks.
898 .Dq snooping .
904 .Dv right2left .
909 .Dv left2right .
914 to left.
916 Encapsulates/de-encapsulates frames encoded according to RFC 1490.
920 for each protocol (i.e. IP, PPP, etc.).
922 Encapsulates/de-encapsulates Frame Relay frames.
926 for each DLCI.
930 (link management interface) operations and packets.
932 is in use at the exchange.
934 This node is also a line discipline.
936 allowing a tty to appear as a netgraph node.
939 character.
942 according to RFC 1662.
944 type for supporting PPP links over asynchronous serial lines.
946 This node is also a system networking interface.
947 It has hooks representing each protocol family (IP, AppleTalk, etc.)
949 .Xr ifconfig 8 .
953 etc.
957 to it (e.g.,
958 .Dv NGM_NODEINFO ) .
961 will be returned.
963 All data messages are mbuf chains with the M_PKTHDR flag set.
965 Nodes are responsible for freeing what they allocate.
969 Mbufs sent across a data link are never to be freed by the sender.
971 Any meta-data information traveling with the data has the same restriction.
974 passed onwards, but the caller will never free it.
984 are freed by the callee.
987 recipient should copy them if it wants to keep that information.
991 .It In netgraph/netgraph.h
994 nodes.
995 .It In netgraph/ng_message.h
998 messages.
999 .It In netgraph/socket/ng_socket.h
1002 socket type nodes.
1003 .It In netgraph/{type}/ng_{type}.h
1007 nodes, including the type cookie definition.
1008 .It Pa /boot/kernel/netgraph.ko
1009 Netgraph subsystem loadable KLD module.
1010 .It Pa /boot/kernel/ng_{type}.ko
1011 Loadable KLD module for node type {type}.
1015 to interact with the netgraph system.
1018 for details.
1024 are available to assist manual configuration and debugging.
1026 There are a few useful techniques for debugging new node types.
1028 makes debugging easier.
1034 .Xr nghook 8 .
1067 system was designed and first implemented at Whistle Communications, Inc.\&
1070 customized for the Whistle InterJet.
1072 .Fx 3.4 .
1075 .An Julian Elischer Aq Mt julian@FreeBSD.org ,
1077 .An Archie Cobbs Aq Mt archie@FreeBSD.org .