Module Name: src
Committed By: wiz
Date: Sun Aug 22 20:36:09 UTC 2010
Modified Files:
src/share/man/man9: npf_ncode.9
Log Message:
Add more articles and more formatting.
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/npf_ncode.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/npf_ncode.9
diff -u src/share/man/man9/npf_ncode.9:1.1 src/share/man/man9/npf_ncode.9:1.2
--- src/share/man/man9/npf_ncode.9:1.1 Sun Aug 22 18:56:20 2010
+++ src/share/man/man9/npf_ncode.9 Sun Aug 22 20:36:09 2010
@@ -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
.\" -----
