diff options
Diffstat (limited to 'share/man/man4/netgraph.4')
-rw-r--r-- | share/man/man4/netgraph.4 | 200 |
1 files changed, 137 insertions, 63 deletions
diff --git a/share/man/man4/netgraph.4 b/share/man/man4/netgraph.4 index 46cc658..546aeed 100644 --- a/share/man/man4/netgraph.4 +++ b/share/man/man4/netgraph.4 @@ -80,25 +80,37 @@ to interact with other nodes in a well defined manner. Each node has a .Em type , which is a static property of the node determined at node creation time. -A node's type is described by a unique ASCII type name. +A node's type is described by a unique +.Tn ASCII +type name. The type implies what the node does and how it may be connected to other nodes. .Pp In object-oriented language, types are classes and nodes are instances of their respective class. All node types are subclasses of the generic node type, and hence inherit certain common functionality and capabilities -(e.g., the ability to have an ASCII name). +(e.g., the ability to have an +.Tn ASCII +name). .Pp -Nodes may be assigned a globally unique ASCII name which can be +Nodes may be assigned a globally unique +.Tn ASCII +name which can be used to refer to the node. -The name must not contain the characters ``.'' or ``:'' and is limited to +The name must not contain the characters +.Dq \&. +or +.Dq \&: +and is limited to .Dv "NG_NODELEN + 1" characters (including NUL byte). .Pp Each node instance has a unique .Em ID number which is expressed as a 32-bit hex value. This value may be used to -refer to a node when there is no ASCII name assigned to it. +refer to a node when there is no +.Tn ASCII +name assigned to it. .Sh Hooks Nodes are connected to other nodes by connecting a pair of .Em hooks , @@ -110,9 +122,15 @@ Hooks have these properties: .Pp .Bl -bullet -compact -offset 2n .It -A hook has an ASCII name which is unique among all hooks +A hook has an +.Tn ASCII +name which is unique among all hooks on that node (other hooks on other nodes may have the same name). -The name must not contain a ``.'' or a ``:'' and is +The name must not contain a +.Dq \&. +or a +.Dq \&: +and is limited to .Dv "NG_HOOKLEN + 1" characters (including NUL byte). @@ -123,7 +141,9 @@ removing either hook destroys both hooks. .El .Pp A node may decide to assign special meaning to some hooks. -For example, connecting to the hook named ``debug'' might trigger +For example, connecting to the hook named +.Dq debug +might trigger the node to start sending debugging information to that hook. .Sh Data Flow Two types of information flow between nodes: data messages and @@ -137,7 +157,8 @@ directly to some arbitrary other node. Control messages have a common header format, followed by type-specific data, and are binary structures for efficiency. However, node types also may support conversion of the type specific data between binary and -ASCII for debugging and human interface purposes (see the +.Tn ASCII +for debugging and human interface purposes (see the .Dv NGM_ASCII2BINARY and .Dv NGM_BINARY2ASCII @@ -146,9 +167,13 @@ these conversions. .Pp There are two ways to address a control message. If there is a sequence of edges connecting the two nodes, the message -may be ``source routed'' by specifying the corresponding sequence +may be +.Dq source routed +by specifying the corresponding sequence of hooks as the destination address for the message (relative -addressing). Otherwise, the recipient node global ASCII name +addressing). Otherwise, the recipient node global +.Tn ASCII +name (or equivalent ID based name) is used as the destination address for the message (absolute addressing). The two types of addressing may be combined, by specifying an absolute start node and a sequence @@ -156,7 +181,9 @@ of hooks. .Pp Messages often represent commands that are followed by a reply message in the reverse direction. To facilitate this, the recipient of a -control message is supplied with a ``return address'' that is suitable +control message is supplied with a +.Dq return address +that is suitable for addressing a reply. .Pp Each control message contains a 32 bit value called a @@ -167,7 +194,7 @@ that it understands. However, a node may choose to recognize and implement more than one type of message. .Sh Netgraph is Functional In order to minimize latency, most -.Nm netgraph +.Nm operations are functional. That is, data and control messages are delivered by making function calls rather than by using queues and mailboxes. For example, if node @@ -175,7 +202,9 @@ A wishes to send a data mbuf to neighboring node B, it calls the generic .Nm data delivery function. This function in turn locates -node B and calls B's ``receive data'' method. While this mode of operation +node B and calls B's +.Dq receive data +method. While this mode of operation results in good performance, it has a few implications for node developers: .Pp @@ -186,13 +215,13 @@ may need to allow for the possibility of receiving a returning message before the original delivery function call returns. .It Netgraph nodes and support routines generally run at -.Dv "splnet()" . +.Fn splnet . However, some nodes may want to send data and control messages from a different priority level. Netgraph supplies queueing routines which utilize the NETISR system to move message delivery to -.Dv "splnet()" . +.Fn splnet . Note that messages are always received at -.Dv "splnet()" . +.Fn splnet . .It It's possible for an infinite loop to occur if the graph contains cycles. .El @@ -215,7 +244,7 @@ which is both a netgraph node and a BSD socket in the protocol family .Dv PF_NETGRAPH . Socket nodes allow user processes to participate in -.Nm netgraph . +.Nm Ns . Other nodes communicate with socket nodes using the usual methods, and the node hides the fact that it is also passing information to and from a cooperating user process. @@ -225,7 +254,7 @@ a node interface to the hardware. .Sh Node Methods Nodes are notified of the following actions via function calls to the following node methods (all at -.Dv "splnet()" ) +.Fn splnet ) and may accept or reject that action (by returning the appropriate error code): .Bl -tag -width xxx @@ -235,7 +264,9 @@ allowed, the constructor must call the generic node creation function (in object-oriented terms, the superclass constructor) and then allocate any special resources it needs. For nodes that correspond to hardware, this is typically done during the device -attach routine. Often a global ASCII name corresponding to the +attach routine. Often a global +.Tn ASCII +name corresponding to the device name is assigned here as well. .It Creation of a new hook The hook is created and tentatively @@ -270,7 +301,7 @@ An mbuf chain is passed to the node. The node is notified on which hook the data arrived, and can use this information in its processing decision. The node must must always -.Dv m_freem() +.Fn m_freem the mbuf chain on completion or error, or pass it on to another node (or kernel module) which will then be responsible for freeing it. .Pp @@ -280,13 +311,13 @@ structure describing meta-data about the message .Dv NULL if there is no additional information. The format for this information is described in -.Dv netgraph.h . +.Pa netgraph.h . The memory for meta-data must allocated via -.Dv malloc() +.Fn malloc with type .Dv M_NETGRAPH . As with the data itself, it is the receiver's responsibility to -.Dv free() +.Fn free the meta-data. If the mbuf chain is freed the meta-data must be freed at the same time. If the meta-data is freed but the real data on is passed on, then a @@ -324,14 +355,14 @@ to point to the reply. Then when the control message delivery function returns, the caller can check if this pointer has been made non-NULL, and if so then it points to the reply message allocated via -.Dv malloc() +.Fn malloc and containing the synchronous response. In both directions, (request and response) it is up to the receiver of that message to -.Dv free() +.Fn free the control message buffer. All control messages and replies are allocated with -.Dv malloc() +.Fn malloc type .Dv M_NETGRAPH . .El @@ -339,7 +370,9 @@ type Much use has been made of reference counts, so that nodes being free'd of all references are automatically freed, and this behaviour has been tested and debugged to present a consistent and trustworthy -framework for the ``type module'' writer to use. +framework for the +.Dq type module +writer to use. .Sh Addressing The .Nm @@ -358,7 +391,11 @@ A relative address includes only the sequence of hook names, implicitly starting hook traversal at the local node. .Pp There are a couple of special possibilities for the node name. -The name ``.'' (referred to as ``.:'') always refers to the local node. +The name +.Dq \&. +(referred to as +.Dq \&.: ) +always refers to the local node. Also, nodes that have no global name may be addressed by their ID numbers, by enclosing the hex representation of the ID number within square brackets. Here are some examples of valid netgraph addresses: @@ -560,19 +597,22 @@ be changed. The de facto method for generating unique type cookies is to take the seconds from the epoch at the time the header file is written (i.e., the output of -.Dv "date -u +'%s'" ")." +.Dv "date -u +'%s'" ) . .Pp There is a predefined typecookie .Dv NGM_GENERIC_COOKIE -for the ``generic'' node type, and +for the +.Dq generic +node type, and a corresponding set of generic messages which all nodes understand. The handling of these messages is automatic. .It Dv command The identifier for the message command. This is type specific, and is defined in the same header file as the typecookie. .It Dv cmdstr -Room for a short human readable version of ``command'' (for debugging -purposes only). +Room for a short human readable version of +.Dq command +(for debugging purposes only). .El .Pp Some modules may choose to implement messages from more than one @@ -580,25 +620,34 @@ of the header files and thus recognize more than one type cookie. .Sh Control Message ASCII Form Control messages are in binary format for efficiency. However, for debugging and human interface purposes, and if the node type supports -it, control messages may be converted to and from an equivalent ASCII -form. The ASCII form is similar to the binary form, with two exceptions: +it, control messages may be converted to and from an equivalent +.Tn ASCII +form. The +.Tn ASCII +form is similar to the binary form, with two exceptions: .Pp .Bl -tag -compact -width xxx .It o The .Dv cmdstr -header field must contain the ASCII name of the command, corresponding to the +header field must contain the +.Tn ASCII +name of the command, corresponding to the .Dv cmd header field. .It o The .Dv args -field contains a NUL-terminated ASCII string version of the message arguments. +field contains a NUL-terminated +.Tn ASCII +string version of the message arguments. .El .Pp In general, the arguments field of a control messgage can be any arbitrary C data type. Netgraph includes parsing routines to support -some pre-defined datatypes in ASCII with this simple syntax: +some pre-defined datatypes in +.Tn ASCII +with this simple syntax: .Pp .Bl -tag -compact -width xxx .It o @@ -616,24 +665,28 @@ does not have an explicit index, the index is implicitly the previous element's index plus one. .It o Structures are enclosed in curly braces, and each field is specified -in the form ``fieldname=value''. +in the form +.Dq fieldname=value . .It o Any array element or structure field whose value is equal to its -``default value'' may be omitted. For integer types, the default value +.Dq default value +may be omitted. For integer types, the default value is usually zero; for string types, the empty string. .It o Array elements and structure fields may be specified in any order. .El .Pp Each node type may define its own arbitrary types by providing -the necessary routines to parse and unparse. ASCII forms defined +the necessary routines to parse and unparse. +.Tn ASCII +forms defined for a specific node type are documented in the documentation for that node type. .Sh Generic Control Messages There are a number of standard predefined messages that will work for any node, as they are supported directly by the framework itself. These are defined in -.Dv ng_message.h +.Pa ng_message.h along with the basic layout of messages and other similar information. .Bl -tag -width xxx .It Dv NGM_CONNECT @@ -655,7 +708,9 @@ is the default for nodes created using the method. Such nodes can only be addressed relatively or by their ID number. .It Dv NGM_RMHOOK Ask the node to break a hook connection to one of its neighbours. -Both nodes will have their ``disconnect'' method invoked. +Both nodes will have their +.Dq disconnect +method invoked. Either node may elect to totally shut down as a result. .It Dv NGM_NODEINFO Asks the target node to describe itself. The four returned fields @@ -688,12 +743,16 @@ elect to not support this message. The text response must be less than bytes in length (presently 1024). This can be used to return general status information in human readable form. .It Dv NGM_BINARY2ASCII -This message converts a binary control message to its ASCII form. +This message converts a binary control message to its +.Tn ASCII +form. The entire control message to be converted is contained within the arguments field of the .Dv Dv NGM_BINARY2ASCII message itself. If successful, the reply will contain the same control -message in ASCII form. +message in +.Tn ASCII +form. A node will typically only know how to translate messages that it itself understands, so the target node of the .Dv NGM_BINARY2ASCII @@ -701,7 +760,9 @@ is often the same node that would actually receive that message. .It Dv NGM_ASCII2BINARY The opposite of .Dv NGM_BINARY2ASCII . -The entire control message to be converted, in ASCII form, is contained +The entire control message to be converted, in +.Tn ASCII +form, is contained in the arguments section of the .Dv NGM_ASCII2BINARY and need only have the @@ -765,20 +826,20 @@ node of unknown type is made, .Nm will attempt to load the KLD module -.Dv ng_type.ko . +.Pa ng_type.ko . .Pp Types can also be installed at boot time, as certain device drivers may want to export each instance of the device as a netgraph node. .Pp In general, new types can be installed at any time from within the kernel by calling -.Dv ng_newtype() , +.Fn ng_newtype , supplying a pointer to the type's .Dv struct ng_type structure. .Pp The -.Dv "NETGRAPH_INIT()" +.Fn NETGRAPH_INIT macro automates this process by using a linker set. .Sh EXISTING NODE TYPES Several node types currently exist. Each is fully documented @@ -808,8 +869,9 @@ calls, using a socket address. .Pp .It HOLE -Responds only to generic messages and is a ``black hole'' for data, -Useful for testing. Always accepts new hooks. +Responds only to generic messages and is a +.Dq black hole +for data, Useful for testing. Always accepts new hooks. .Pp .It ECHO Responds only to generic messages and always echoes data back through the @@ -817,7 +879,9 @@ hook from which it arrived. Returns any non generic messages as their own response. Useful for testing. Always accepts new hooks. .Pp .It TEE -This node is useful for ``snooping.'' It has 4 hooks: +This node is useful for +.Dq snooping . +It has 4 hooks: .Dv left , .Dv right , .Dv left2right , @@ -836,24 +900,31 @@ to left. .Pp .It RFC1490 MUX Encapsulates/de-encapsulates frames encoded according to RFC 1490. -Has a hook for the encapsulated packets (``downstream'') and one hook +Has a hook for the encapsulated packets +.Pq Dq downstream +and one hook for each protocol (i.e., IP, PPP, etc.). .Pp .It FRAME RELAY MUX Encapsulates/de-encapsulates Frame Relay frames. -Has a hook for the encapsulated packets (``downstream'') and one hook +Has a hook for the encapsulated packets +.Pq Dq downstream +and one hook for each DLCI. .Pp .It FRAME RELAY LMI Automatically handles frame relay -``LMI'' (link management interface) operations and packets. +.Dq LMI +(link management interface) operations and packets. Automatically probes and detects which of several LMI standards is in use at the exchange. .Pp .It TTY This node is also a line discipline. It simply converts between mbuf frames and sequential serial data, allowing a tty to appear as a netgraph -node. It has a programmable ``hotkey'' character. +node. It has a programmable +.Dq hotkey +character. .Pp .It ASYNC This node encapsulates and de-encapsulates asynchronous frames @@ -891,14 +962,14 @@ It might be freed by any node the data passes through, and a .Dv NULL passed onwards, but the caller will never free it. Two macros -.Dv "NG_FREE_META(meta)" +.Fn NG_FREE_META "meta" and -.Dv "NG_FREE_DATA(m, meta)" +.Fn NG_FREE_DATA "m" "meta" should be used if possible to free data and meta data (see -.Dv netgraph.h ")." +.Pa netgraph.h ) . .It 3 Messages sent using -.Dv ng_send_message() +.Fn ng_send_message are freed by the callee. As in the case above, the addresses associated with the message are freed by whatever allocated them so the recipient should copy them if it wants to keep that information. @@ -974,7 +1045,10 @@ and The .Nm system was designed and first implemented at Whistle Communications, Inc. -in a version FreeBSD 2.2 customized for the Whistle InterJet. +in a version +.Fx 2.2 +customized for the Whistle InterJet. .Sh AUTHORS -Julian Elischer <julian@whistle.com>, with contributions by -Archie Cobbs <archie@whistle.com>. +.An Julian Elischer Aq julian@whistle.com , +with contributions by +.An Archie Cobbs Aq archie@whistle.com . |