36c36
< .\" $FreeBSD: head/share/man/man4/netgraph.4 69027 2000-11-22 09:35:58Z ru $
---
> .\" $FreeBSD: head/share/man/man4/netgraph.4 69922 2000-12-12 18:52:14Z julian $
140a141,145
> .It
> A hook can be set into a state where incoming packets are always queued
> by the input queuing system, rather than being delivered directly. This
> is used when the two joined nodes need to be decoupled, e.g. if they are
> running at different processor priority levels. (spl)
168c173
< There are two ways to address a control message. If
---
> There are three ways to address a control message. If
173,174c178
< of hooks as the destination address for the message (relative
< addressing). Otherwise, the recipient node global
---
> of
175a180,184
> hook names as the destination address for the message (relative
> addressing). If the destination is adjacent to the source, then the source
> node may simply specify (as a pointer in the code) the hook across which the
> message should be sent. Otherwise, the recipient node global
> .Tn ASCII
178c187,189
< for the message (absolute addressing). The two types of addressing
---
> for the message (absolute addressing). The two types of
> .Tn ASCII
> addressing
180c191,194
< of hooks.
---
> of hooks. Only the
> .Tn ASCII
> addressing modes are available to control programs outside the kernel,
> as use of direct pointers is limited of course to kernel modules.
186,187c200,207
< that is suitable
< for addressing a reply.
---
> that is suitable for addressing a reply.
> In addition, depending on the topology of
> the graph and whether the source has requested it, a pointer to a
> pointer that can be read by the source node may also be supplied.
> This allows the destination node to directly respond in a
> synchronous manner when control returns to the source node, by
> simply pointing the supplied pointer to the response message.
> Such synchronous message responses are more efficient but are not always possible.
196,197c216,218
< If message is delivered to an address that implies that it arrived
< at that node through a particular hook, that hook is identified to the
---
> If a message is delivered to an address that implies that it arrived
> at that node through a particular hook, (as opposed to having been directly
> addressed using its ID or global name), then that hook is identified to the
199c220,229
< a node decide that this is required.
---
> a node decide that this is required, in much the same way that data packets
> are passed around between nodes. A set of standard
> messages for flow control and link management purposes are
> defined by the base system that are usually
> passed around in this manner. Flow control message would usually travel
> in the opposite direction to the data to which they pertain.
> .Pp
> Since flow control packets can also result from data being sent, it is also
> possible to return a synchronous message response to a data packet being
> sent between nodes. (See later).
212c242
< method.
---
> method. There are exceptions to this.
219c249,251
< macro, in which case, the second node should just discard rejected packets.
---
> and
> .Fn NG_SEND_DATA_ONLY
> macros, in which case, the second node should just discard rejected packets.
240,241c272,273
< from a different priority level. Netgraph supplies queueing routines which
< utilize the NETISR system to move message delivery to
---
> from a different priority level. Netgraph supplies a mechanism which
> utilizes the NETISR system to move message and data delivery to
245c277
< however any interaction with nodes running at splnet MUST be achievd via the
---
> however any interaction with nodes running at splnet MUST be achieved via the
306c338,341
< the connection. Tear-down is automatic.
---
> the connection. Tear-down is automatic. This is also the time at which
> a node may decide whether to set a particular hook (or its peer) into
> .Em queuing
> mode.
323c358
< Three other methods are also supported by all nodes:
---
> Two other methods are also supported by all nodes:
345c380
< .Pa netgraph.h .
---
> .Pa sys/netgraph/netgraph.h .
364c399,410
< NETISR system (see below).
---
> NETISR system (see below). It achieves this by setting the
> .Dv HK_QUEUE
> flag in the flags word of the hook on which that data will arrive.
> The infrastructure will respect that bit and queue the data for delivery at
> a later time, rather than deliver it directly. A node may decide to set
> the bit on the
> .Em peer
> node, so that it's own output packets are queued. This is used
> by device drivers running at different processor priorities to transfer
> packet delivery to the splnet() level at which the bulk of
> .Nm
> runs.
366,367c412,414
< The structure and use of meta-data is still experimental, but is presently used in
< frame-relay to indicate that management packets should be queued for transmission
---
> The structure and use of meta-data is still experimental, but is
> presently used in frame-relay to indicate that management packets
> should be queued for transmission
371,380c418,422
< .It Receive queued data message
< Usually this will be the same function as
< .Em Receive data message.
< This is the entry point called when a data message is being handed to
< the node after having been queued in the NETISR system.
< This allows a node to decide in the
< .Em Receive data message
< method that a message should be deferred and queued,
< and be sure that when it is processed from the queue,
< it will not be queued again.
---
> The node may also receive information allowing it to send a synchronous
> message response to one of the originators of the data. it is envisionned
> that such a message would contain error or flow-control information.
> Standard messages for these purposes have been defined in
> .Pa sys/netgraph/netgraph.h .
448c490
< [f057cd80]:hook1
---
> [d80]:hook1
500a543,561
> In a similar way, flow control messages may be routed in the reverse
> direction to outgoing data. For example a "buffer nearly full" message from
> .Em "Frame1:
> would be passed to node
> .Em B
> which might decide to send similar messages to both nodes
> .Em C
> and
> .Em D .
> The nodes would use
> .Em "Direct hook pointer"
> addressing to route the messages. The message may have travelled from
> .Em "Frame1:
> to
> .Em B
> as a synchronous reply, saving time and cycles.
>
>
> .Pp
515c576,581
< Interesting members of the node and hook structures are shown below:
---
> Interesting members of the node and hook structures are shown below
> however you should
> check
> .Pa sys/netgraph/netgraph.h
> on your system for more up-to-date versions.
>
550c616
< Node types are described by these structures:
---
> Node types are described by the structures below:
573,576c639,642
< struct ng_mesg *msg, /* The message */
< const char *retaddr, /* Return address */
< struct ng_mesg **resp /* Synchronous response */
< hook_p lasthook); /* last hook traversed */
---
> struct ng_mesg *msg, /* The message */
> const char *retaddr, /* Return address */
> struct ng_mesg **resp /* Synchronous response */
> hook_p lasthook); /* last hook traversed */
579,580c645,646
< hook_p hook, /* Pre-allocated struct */
< const char *name); /* Name for new hook */
---
> hook_p hook, /* Pre-allocated struct */
> const char *name); /* Name for new hook */
585,588c651,655
< struct mbuf *m, /* The data in an mbuf */
< meta_p meta, /* Meta-data, if any */
< struct mbuf **ret_m, /* return data here */
< meta_p *ret_meta); /* return Meta-data here */
---
> struct mbuf *m, /* The data in an mbuf */
> meta_p meta, /* Meta-data, if any */
> struct mbuf **ret_m, /* return data here */
> meta_p *ret_meta, /* return Meta-data here */
> struct ng_message **resp); /* Synchronous reply info */
614c681
< #define NG_VERSION 1 /* Netgraph version */
---
> #define NG_VERSION 3 /* Netgraph version */
830a898,914
>
> .Sh Flow Control Messages
> In addition to the control messages that affect nodes with respect to the
> graph, there are also a number of
> .Em Flow-control
> messages defined. At present these are
> .Em NOT
> handled automatically by the system, so
> nodes need to handle them if they are going to be used in a graph utilising
> flow control, and will be in the likely path of these messages. The
> default action of a node that doesn't understand these messages should
> be to pass them onto the next node. Hopefully some helper functions
> will assist in this eventually. These messages are also defined in
> .Pa sys/netgraph/ng_message.h
> and have a separate cookie
> .Em NG_FLOW_COOKIE
> to help identify them. They will not be covered in depth here.
995a1080,1108
> .It ONE2MANY
> This node implements a simple round-robin multiplexer. It can be used
> for example to make several LAN ports act together to get a higher speed
> link between two machines.
> .It Various PPP related nodes.
> There is a full multilink PPP implementation that runs in Netgraph.
> The
> .Em Mpd
> port can use these modules to make a very low latency high
> capacity ppp system. It also supports
> .Em PPTP
> vpns using the
> .Em PPTP
> node.
> .It PPPOE
> A server and client side implememtation of PPPoE. Used in conjunction with
> either
> .Xr ppp 8
> or the
> .Em mpd port.
> .It BRIDGE
> This node, togther with the ethernet nodes allows a very flexible
> bridging system to be implemented.
> .It KSOCKET
> This intriguing node looks like a socket to the system but diverts
> all data to and from the netgraph system for further processing. This allows
> such things as UDP tunnels to be almost trivially implemented from the
> command line.
>
996a1110,1111
> .Pp
> Refer to the section at the end of this man page for more nodes types.
1076a1192,1195
> .Pp
> Also look in /usr/share/examples/netgraph for solutions to several
> common networking problems, solved using
> .Nm .
1080a1200
> .Xr ng_bridge 4 ,
1084a1205
> .Xr ng_ether 4 ,
1092a1214
> .Xr ng_pptpgre 4 ,
< .\" $FreeBSD: head/share/man/man4/netgraph.4 69027 2000-11-22 09:35:58Z ru $
---
> .\" $FreeBSD: head/share/man/man4/netgraph.4 69922 2000-12-12 18:52:14Z julian $
140a141,145
> .It
> A hook can be set into a state where incoming packets are always queued
> by the input queuing system, rather than being delivered directly. This
> is used when the two joined nodes need to be decoupled, e.g. if they are
> running at different processor priority levels. (spl)
168c173
< There are two ways to address a control message. If
---
> There are three ways to address a control message. If
173,174c178
< of hooks as the destination address for the message (relative
< addressing). Otherwise, the recipient node global
---
> of
175a180,184
> hook names as the destination address for the message (relative
> addressing). If the destination is adjacent to the source, then the source
> node may simply specify (as a pointer in the code) the hook across which the
> message should be sent. Otherwise, the recipient node global
> .Tn ASCII
178c187,189
< for the message (absolute addressing). The two types of addressing
---
> for the message (absolute addressing). The two types of
> .Tn ASCII
> addressing
180c191,194
< of hooks.
---
> of hooks. Only the
> .Tn ASCII
> addressing modes are available to control programs outside the kernel,
> as use of direct pointers is limited of course to kernel modules.
186,187c200,207
< that is suitable
< for addressing a reply.
---
> that is suitable for addressing a reply.
> In addition, depending on the topology of
> the graph and whether the source has requested it, a pointer to a
> pointer that can be read by the source node may also be supplied.
> This allows the destination node to directly respond in a
> synchronous manner when control returns to the source node, by
> simply pointing the supplied pointer to the response message.
> Such synchronous message responses are more efficient but are not always possible.
196,197c216,218
< If message is delivered to an address that implies that it arrived
< at that node through a particular hook, that hook is identified to the
---
> If a message is delivered to an address that implies that it arrived
> at that node through a particular hook, (as opposed to having been directly
> addressed using its ID or global name), then that hook is identified to the
199c220,229
< a node decide that this is required.
---
> a node decide that this is required, in much the same way that data packets
> are passed around between nodes. A set of standard
> messages for flow control and link management purposes are
> defined by the base system that are usually
> passed around in this manner. Flow control message would usually travel
> in the opposite direction to the data to which they pertain.
> .Pp
> Since flow control packets can also result from data being sent, it is also
> possible to return a synchronous message response to a data packet being
> sent between nodes. (See later).
212c242
< method.
---
> method. There are exceptions to this.
219c249,251
< macro, in which case, the second node should just discard rejected packets.
---
> and
> .Fn NG_SEND_DATA_ONLY
> macros, in which case, the second node should just discard rejected packets.
240,241c272,273
< from a different priority level. Netgraph supplies queueing routines which
< utilize the NETISR system to move message delivery to
---
> from a different priority level. Netgraph supplies a mechanism which
> utilizes the NETISR system to move message and data delivery to
245c277
< however any interaction with nodes running at splnet MUST be achievd via the
---
> however any interaction with nodes running at splnet MUST be achieved via the
306c338,341
< the connection. Tear-down is automatic.
---
> the connection. Tear-down is automatic. This is also the time at which
> a node may decide whether to set a particular hook (or its peer) into
> .Em queuing
> mode.
323c358
< Three other methods are also supported by all nodes:
---
> Two other methods are also supported by all nodes:
345c380
< .Pa netgraph.h .
---
> .Pa sys/netgraph/netgraph.h .
364c399,410
< NETISR system (see below).
---
> NETISR system (see below). It achieves this by setting the
> .Dv HK_QUEUE
> flag in the flags word of the hook on which that data will arrive.
> The infrastructure will respect that bit and queue the data for delivery at
> a later time, rather than deliver it directly. A node may decide to set
> the bit on the
> .Em peer
> node, so that it's own output packets are queued. This is used
> by device drivers running at different processor priorities to transfer
> packet delivery to the splnet() level at which the bulk of
> .Nm
> runs.
366,367c412,414
< The structure and use of meta-data is still experimental, but is presently used in
< frame-relay to indicate that management packets should be queued for transmission
---
> The structure and use of meta-data is still experimental, but is
> presently used in frame-relay to indicate that management packets
> should be queued for transmission
371,380c418,422
< .It Receive queued data message
< Usually this will be the same function as
< .Em Receive data message.
< This is the entry point called when a data message is being handed to
< the node after having been queued in the NETISR system.
< This allows a node to decide in the
< .Em Receive data message
< method that a message should be deferred and queued,
< and be sure that when it is processed from the queue,
< it will not be queued again.
---
> The node may also receive information allowing it to send a synchronous
> message response to one of the originators of the data. it is envisionned
> that such a message would contain error or flow-control information.
> Standard messages for these purposes have been defined in
> .Pa sys/netgraph/netgraph.h .
448c490
< [f057cd80]:hook1
---
> [d80]:hook1
500a543,561
> In a similar way, flow control messages may be routed in the reverse
> direction to outgoing data. For example a "buffer nearly full" message from
> .Em "Frame1:
> would be passed to node
> .Em B
> which might decide to send similar messages to both nodes
> .Em C
> and
> .Em D .
> The nodes would use
> .Em "Direct hook pointer"
> addressing to route the messages. The message may have travelled from
> .Em "Frame1:
> to
> .Em B
> as a synchronous reply, saving time and cycles.
>
>
> .Pp
515c576,581
< Interesting members of the node and hook structures are shown below:
---
> Interesting members of the node and hook structures are shown below
> however you should
> check
> .Pa sys/netgraph/netgraph.h
> on your system for more up-to-date versions.
>
550c616
< Node types are described by these structures:
---
> Node types are described by the structures below:
573,576c639,642
< struct ng_mesg *msg, /* The message */
< const char *retaddr, /* Return address */
< struct ng_mesg **resp /* Synchronous response */
< hook_p lasthook); /* last hook traversed */
---
> struct ng_mesg *msg, /* The message */
> const char *retaddr, /* Return address */
> struct ng_mesg **resp /* Synchronous response */
> hook_p lasthook); /* last hook traversed */
579,580c645,646
< hook_p hook, /* Pre-allocated struct */
< const char *name); /* Name for new hook */
---
> hook_p hook, /* Pre-allocated struct */
> const char *name); /* Name for new hook */
585,588c651,655
< struct mbuf *m, /* The data in an mbuf */
< meta_p meta, /* Meta-data, if any */
< struct mbuf **ret_m, /* return data here */
< meta_p *ret_meta); /* return Meta-data here */
---
> struct mbuf *m, /* The data in an mbuf */
> meta_p meta, /* Meta-data, if any */
> struct mbuf **ret_m, /* return data here */
> meta_p *ret_meta, /* return Meta-data here */
> struct ng_message **resp); /* Synchronous reply info */
614c681
< #define NG_VERSION 1 /* Netgraph version */
---
> #define NG_VERSION 3 /* Netgraph version */
830a898,914
>
> .Sh Flow Control Messages
> In addition to the control messages that affect nodes with respect to the
> graph, there are also a number of
> .Em Flow-control
> messages defined. At present these are
> .Em NOT
> handled automatically by the system, so
> nodes need to handle them if they are going to be used in a graph utilising
> flow control, and will be in the likely path of these messages. The
> default action of a node that doesn't understand these messages should
> be to pass them onto the next node. Hopefully some helper functions
> will assist in this eventually. These messages are also defined in
> .Pa sys/netgraph/ng_message.h
> and have a separate cookie
> .Em NG_FLOW_COOKIE
> to help identify them. They will not be covered in depth here.
995a1080,1108
> .It ONE2MANY
> This node implements a simple round-robin multiplexer. It can be used
> for example to make several LAN ports act together to get a higher speed
> link between two machines.
> .It Various PPP related nodes.
> There is a full multilink PPP implementation that runs in Netgraph.
> The
> .Em Mpd
> port can use these modules to make a very low latency high
> capacity ppp system. It also supports
> .Em PPTP
> vpns using the
> .Em PPTP
> node.
> .It PPPOE
> A server and client side implememtation of PPPoE. Used in conjunction with
> either
> .Xr ppp 8
> or the
> .Em mpd port.
> .It BRIDGE
> This node, togther with the ethernet nodes allows a very flexible
> bridging system to be implemented.
> .It KSOCKET
> This intriguing node looks like a socket to the system but diverts
> all data to and from the netgraph system for further processing. This allows
> such things as UDP tunnels to be almost trivially implemented from the
> command line.
>
996a1110,1111
> .Pp
> Refer to the section at the end of this man page for more nodes types.
1076a1192,1195
> .Pp
> Also look in /usr/share/examples/netgraph for solutions to several
> common networking problems, solved using
> .Nm .
1080a1200
> .Xr ng_bridge 4 ,
1084a1205
> .Xr ng_ether 4 ,
1092a1214
> .Xr ng_pptpgre 4 ,