[src/trunk]: src/share/man/man9 Add more articles and more formatting.

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/54d66b80cea9
branches:  trunk
changeset: 757278:54d66b80cea9
user:      wiz <wiz%NetBSD.org@localhost>
date:      Sun Aug 22 20:36:09 2010 +0000

description:
Add more articles and more formatting.

diffstat:

 share/man/man9/npf_ncode.9 |  132 +++++++++++++++++++++++---------------------
 1 files changed, 69 insertions(+), 63 deletions(-)

diffs (235 lines):

diff -r a6ad47b63237 -r 54d66b80cea9 share/man/man9/npf_ncode.9
--- a/share/man/man9/npf_ncode.9        Sun Aug 22 18:56:18 2010 +0000
+++ b/share/man/man9/npf_ncode.9        Sun Aug 22 20:36:09 2010 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: npf_ncode.9,v 1.1 2010/08/22 18:56:20 rmind Exp $
+.\"    $NetBSD: npf_ncode.9,v 1.2 2010/08/22 20:36:09 wiz Exp $
 .\"
 .\" Copyright (c) 2009-2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -44,36 +44,40 @@
 .Sh DESCRIPTION
 The NPF n-code processor is a general purpose engine to inspect network
 packets, which are abstracted as chained buffers.
-.Pp
 .Sh FUNCTIONS
 .Fn npf_ncode_process
 performs n-code processing using data of the specified packet.
 .Fa ncode
-is address to a validated n-code memory block.
-N-code memory address should be 32 bit word aligned.
+is the address to a validated n-code memory block.
+N-code memory addresses should be 32-bit word aligned.
 .Fa nbuf
-is an opaque network buffer on which n-code processor will operate.
+is an opaque network buffer on which the n-code processor will operate.
 .Fa layer
-specifies at which network layer buffer is passed, it can be either
-NPF_LAYER_L2 or NPF_LAYER_L3.
-This value is initally set in R0 register and can be checked by the
-n-code.
-Contents of other registers are unspecified.
+specifies at which network layer the buffer is passed, it can be either
+.Dv NPF_LAYER_L2
+or
+.Dv NPF_LAYER_L3 .
+This value is initially set in the R0 register and can be checked
+by the n-code.
+The contents of other registers are unspecified.
 .Pp
-Function returns a value from the n-code.
+.Fn npf_ncode_process
+returns a value from the n-code.
 .Pp
 .Fn npf_ncode_validate
 performs n-code validation.
 .Fa ncode
-is address to a n-code memory block.
+is the address to an n-code memory block.
 .Fa sz
-is the size of memory block.
+is the size of the memory block.
 .Fa errat
-is the word number in the n-code where error is detected.
-If no error, this value is undefined.
+is the word number in the n-code where the error is detected.
+If no error is found, this value is undefined.
 .Pp
-On successful validation, function returns 0.
-Otherwise, may return one of the following error codes:
+On successful validation, the
+.Fn npf_ncode_validate
+function returns 0.
+Otherwise, it may return one of the following error codes:
 .Bl -tag -width [NPF_ERR_OPCODE]
 .It Bq Er NPF_ERR_OPCODE
 Invalid instruction (unknown opcode).
@@ -89,35 +93,35 @@
 .Pp
 Any untrusted n-code, for example generated by userspace, should be
 validated (once) before allowing to process it.
-.Pp
 .\" -----
 .Sh PROCESSING
 There are two instruction sets: RISC-like and CISC-like.
 Processing is done in words, therefore both instructions (their codes) and
-arguments are always 32 bit long words.
+arguments are always 32-bit long words.
 .Pp
 There are four general purpose registers: R0, R1, R2, R3.
-Each can store 32 bit long words.
+Each can store 32-bit long words.
 Registers are mainly to store values for operations using RISC-like
 instructions.
 CISC-like instructions, however, use them to store return values.
 .Pp
-Processing begins from the first word until it reaches
-NPF_OPCODE_RET
+Processing begins from the first word until it reaches an
+.Dv NPF_OPCODE_RET
 instruction with a return value.
-Instruction pointer can be changed using jump operations, which always
-take relative address, in words.
-Result of last comparison is tracked internally and jump operations should
-be performed immediately after comparison or certain CISC-like instructions.
+The instruction pointer can be changed using jump operations, which always
+take relative addresses, in words.
+The result of last comparison is tracked internally and jump
+operations should be performed immediately after comparison or
+certain CISC-like instructions.
 .Pp
 CISC-like instructions and
-NPF_OPCODE_LOAD
-can be used to load data from network buffer.
-They operate at current network buffer offset, which is initially at
-the beginning of network buffer.
-NPF_OPCODE_ADVR
+.Dv NPF_OPCODE_LOAD
+can be used to load data from network buffers.
+They operate at the current network buffer offset, which is initially at
+the beginning of the network buffer.
+The
+.Dv NPF_OPCODE_ADVR
 instruction can be used to advance the current network buffer offset.
-.Pp
 .\" -----
 .Sh CACHING
 Various packet data is cached during execution of CISC-like instructions
@@ -125,12 +129,12 @@
 If n-code changes the packet data, information in the cache might no
 longer reflect the changes.
 In such case, it is n-code's responsibility to invalidate the cache
-(if necessary) by executing
-NPF_OPCODE_INVL
+(if necessary) by executing the
+.Dv NPF_OPCODE_INVL
 instruction.
 .\" -----
 .Sh INSTRUCTIONS
-Return, advance, jump and tag operations.
+Return, advance, jump, and tag operations.
 .Bl -tag -width indent
 .It Sy 0x00 NPF_OPCODE_RET <return value>
 Finish processing and return passed value.
@@ -140,8 +144,8 @@
 Value represents bytes and cannot be negative or zero.
 .It Sy 0x02 NPF_OPCODE_J <relative address>
 Jump processor to a relative address (from this instruction).
-Address value is the amount of words forwards or backwards.
-It can point only to a valid instruction, at valid boundary.
+The address value is the amount of words forwards or backwards.
+It can point only to a valid instruction, at valid boundaries.
 .It Sy 0x03 NPF_OPCODE_INVL
 Invalidate all data in the packet cache.
 .It Sy 0x04 NPF_OPCODE_TAG <key> <value>
@@ -154,10 +158,10 @@
 .It Sy 0x10 NPF_OPCODE_MOV <value>, <register>
 Set the specified value to a register.
 .It Sy 0x11 NPF_OPCODE_LOAD <length>, <register>
-Load secified length of packet data into the register.
-Data is read starting from the current network buffer offset.
-Operation does not advance the offset after read, however.
-Value of
+Load specified length of packet data into the register.
+The data is read starting from the current network buffer offset.
+The operation does not advance the offset after read, however.
+The value of
 .Fa length
 represents bytes and must be in the range from 1 to 4.
 Returned data is in network byte order.
@@ -168,30 +172,32 @@
 .Bl -tag -width indent
 .It Sy 0x21 NPF_OPCODE_CMP <value>, <register>
 Compare the specified value and value in a register.
-Result is stored internally and can be tested by jump instructions.
+The result is stored internally and can be tested by jump instructions.
 .It Sy 0x22 NPF_OPCODE_CMPR <register>, <register>
 Compare values of two registers.
-Result is stored internally and can be tested by jump instructions.
+The result is stored internally and can be tested by jump instructions.
 .It Sy 0x23 NPF_OPCODE_BEQ <relative address>
-Jump if result of last comparison was "equal".
-Otherwise, continue processing of next instruction.
+Jump if the result of the last comparison was "equal".
+Otherwise, continue processing with the next instruction.
 .It Sy 0x24 NPF_OPCODE_BNE <relative address>
-Jump if result of last comparison was "not equal".
-Otherwise, continue processing of next instruction.
+Jump if the result of last comparison was "not equal".
+Otherwise, continue processing with the next instruction.
 .It Sy 0x25 NPF_OPCODE_BGT <relative address>
-Jump if result of last comparison was "greater than".
-Otherwise, continue processing of next instruction.
+Jump if the result of last comparison was "greater than".
+Otherwise, continue processing with the next instruction.
 .It Sy 0x26 NPF_OPCODE_BLT <relative address>
-Jump if result of last comparison was "less than".
-Otherwise, continue processing of next instruction.
+Jump if the result of last comparison was "less than".
+Otherwise, continue processing with the next instruction.
 .El
 .Pp
 .\" ---
 Bitwise operations.
 .Bl -tag -width indent
 .It Sy 0x30 NPF_OPCODE_AND <value>, <register>
-Perform bitwise AND with a specified value and value in the register.
-Result is stored in the register.
+Perform bitwise
+.Dv AND
+with a specified value and the value in the register.
+The result is stored in the register.
 .El
 .Pp
 .\" -----
@@ -220,20 +226,20 @@
 .\" -
 .It Sy 0xa0 NPF_OPCODE_TCP_PORT        <s/d>, <port range>
 Match the source or destination port with a specified port range.
-Higher 16 bits of second argument represent "from" and lower 16 bits
-represent "to" values of range.
-The 32 bit port range value is host byte order, however the actual
-"from" and "to" values should be in the network byte order.
-Value of the first argument indicates whether source (if 0x1) or
+The higher 16 bits of the second argument represent the "from" and
+the lower 16 bits represent the "to" values of the range.
+The 32-bit port range value is in host byte order, however the actual
+"from" and "to" values should be in network byte order.
+The value of the first argument indicates whether source (if 0x1) or
 destination (if 0x0) port should be matched.
 .\" -
 .It Sy 0xa1 NPF_OPCODE_UDP_PORT <s/d>, <port range>
 Match the source or destination port with a specified port range.
-Higher 16 bits of second argument represent "from" and lower 16 bits
-represent "to" values of range.
-The 32 bit port range value is host byte order, however the actual
-"from" and "to" values should be in the network byte order.
-Value of the first argument indicates whether source (if 0x1) or
+The higher 16 bits of the second argument represent the "from" and
+the lower 16 bits represent the "to" values of range.
+The 32-bit port range value is in host byte order, however the actual
+"from" and "to" values should be in network byte order.
+The value of the first argument indicates whether source (if 0x1) or
 destination (if 0x0) port should be matched.
 .El
 .\" -----