grammar and mdoc fixes;

1 files changed, 123 insertions, 113 deletions

diff --git a/share/man/man4/man4.hppa/pdc.4 b/share/man/man4/man4.hppa/pdc.4
index fee21031e08..227c624e2a4 100644
--- a/share/man/man4/man4.hppa/pdc.4
+++ b/share/man/man4/man4.hppa/pdc.4
@@ -1,4 +1,4 @@
-.\" $OpenBSD: pdc.4,v 1.1 2004/09/14 22:03:29 mickey Exp $
+.\" $OpenBSD: pdc.4,v 1.2 2004/09/27 08:33:21 jmc Exp $
 .\"
 .\" Copyright (c) 2004 Michael Shalayeff
 .\" All rights reserved.
@@ -36,30 +36,29 @@
 The
 .Nm
 driver provides system console services through the PDC
-and also means for calling PDC procedures described later.
-PDC console is used early in the kernel startup before enough kernel
-subsystems has been initialized to directly use the hardware either
-that being serial ports or keyboard and video.
+and also a means for calling PDC procedures, described later.
+The PDC console is used early in the kernel startup before enough kernel
+subsystems have been initialized to directly use the hardware
+i.e. serial ports, keyboard, and video.
 .Pp
-PDC version displayed on system boot is relevant to the particular
-system model and does not necessarily comparable to PDC versions
+The PDC version displayed at system boot is relevant to the particular
+system model and is not necessarily comparable to PDC versions
 on other systems.
 .\" TODO page0 description and entry points
 .Sh PDC PROCEDURES
 PDC procedure calls are all made through a single entry point
-and assume normal C language calling conventions with option
+and assume normal C language calling conventions, with option
 number in the first argument and the return data address in the
-second unless indcated otherwise.
-Each call requires at most 7KB of stack available.
+second, unless indicated otherwise.
+Each call requires at most 7KB of the available stack.
 Here is the list of procedures and options descriptions:
-.Pp
 .Bl -tag -width pdc
 .It Fn pdc "PDC_ADD_VALID" "PDC_ADD_VALID_DFLT" "paddr"
 Perform a read operation attempt at the physical address
 .Ar paddr
-without causing a HPMC thus to verify that physical address is valid
+without causing a HPMC, in order to verify that the address is valid
 and there is a device to respond to it.
-Implementation may choose to call the caller's HPMC handler and
+The implementation may choose to call the caller's HPMC handler and
 raise error conditions on the bus convertors.
 .It Fn pdc "PDC_ALLOC" "PDC_ALLOC_DFLT" "ptr" "size"
 Allocate static storage for IODC use of
@@ -68,14 +67,14 @@ bytes and return the address in a word pointed to by the
 .Ar ptr
 argument.
 There is no way of freeing the storage allocated and thus
-care shal be taken to not exhaust the total allocation limit of 32KB.
+care shall be taken to not exhaust the total allocation limit of 32KB.
 .It Fn pdc "PDC_BLOCK_TLB" "PDC_BTLB_DEFAULT" "ptr"
 Get block TLB parameters into the data area pointed to by the
 .Ar ptr
 argument.
 This includes minimal and maximal entry size and number of fixed and
 variable sized entries in the block TLB.
-Fixed entries have size of power of two and aligned to the size
+Fixed entries have size of power of two and are aligned to the size
 where variable entries can have any size and base address both
 aligned to a page.
 .It Xo
@@ -99,16 +98,16 @@ physicall address
 region length
 .Ar len ,
 access rights
-.Ar acc
+.Ar acc ,
 into the slot number
 .Ar slot .
 .It Fn pdc "PDC_BLOCK_TLB" "PDC_BTLB_PURGE" "sp" "va" "slot" "len"
-Purge one entry from the block TLB specified byt the space ID
+Purge one entry from the block TLB specified by the space ID
 .Ar sp ,
 virtual address
 .Ar va ,
 region length
-.Ar len
+.Ar len ,
 from slot number
 .Ar slot .
 .It Fn pdc "PDC_BLOCK_TLB" "PDC_BTLB_PURGE_ALL"
@@ -119,9 +118,9 @@ Retrieve cache and TLB configuration parameters into the data area
 pointed to by the
 .Ar ptr
 argument.
-Format of the data stores is as follows:
+The format of the data stores is as follows:
 .Bl -column "0x00" "contents" -offset left
-.It "addr" Ta "contents"
+.It Sy "addr" Ta Sy "contents"
 .It "0x00" Ta "I-cache size in bytes"
 .It "0x04" Ta "I-cache configuration"
 .It "0x08" Ta "I-cache base for flushing"
@@ -154,9 +153,9 @@ Format of the data stores is as follows:
 .It "0x74" Ta "DTLB loop size for flushing"
 .El
 .Pp
-Cache configuration word is formatted as follows:
+The cache configuration word is formatted as follows:
 .Bl -column "bit" "len" "contents" -offset left
-.It "bit" "len" "contents"
+.It Sy "bit" "len" "contents"
 .It "0" "12" "reserved"
 .It "13" "3" "set 1 if coherent operation supported"
 .It "16" "2" "flush mode: 0 -- fdc & fic; 1 -- fdc; 2 -- fic; 3 -- either"
@@ -172,16 +171,18 @@ The second word in each of the
 .Ar i_cst ,
 .Ar d_cst ,
 .Ar it_cst ,
+and
 .Ar dt_cst
-arguments specifies the desired coherency opration for instructions cache,
-data cache, instructions TLB and data TLB respectively.
-Data area pointed to by the
-.Ar ptr
-argument receives actual coherent operation state after an attempted change.
-CPU does not support requested operation change should corresponding words
-not match the arguments upon return.
-Currently supported values are zero for uncoherent opration and one
-for coherent operation.
+arguments specifies the desired coherency operation for the instructions cache,
+data cache, instructions TLB, and data TLB, respectively.
+The data area pointed to by the
+.Ar ptr
+argument receives the actual coherent operation state
+after an attempted change.
+The CPU does not support the requested operation change
+should the corresponding words not match the arguments upon return.
+The currently supported values are zero for incoherent operation,
+and one for coherent operation.
 .It Fn pdc "PDC_CACHE" "PDC_CACHE_GETSPIDB" "ptr"
 The word pointed to by the
 .Ar ptr
@@ -191,6 +192,7 @@ Update the chassis display with data given in the
 .Ar display
 argument.
 The bitfields in the word are as follows:
+.Pp
 .Bl -tag -width 0xfffff -compact
 .It 0xe0000
 Specifies the system state.
@@ -215,7 +217,7 @@ all on
 .It 0x10000
 Blank the chassis display.
 .It 0x0f000
-This and the other lower three nibles specify the four hex digits
+This and the other lower three nibbles specify the four hex digits
 to be displayed on the chassis display.
 .El
 .It Fn pdc "PDC_CHASSIS" "PDC_CHASSIS_WARN" "ptr"
@@ -224,10 +226,11 @@ batteries and power supplies.
 A word of data is returned in the area pointed by the
 .Ar ptr
 argument and is described with bitfields:
+.Pp
 .Bl -tag -width 0xff -compact
 .It 0xff000000
 Zero means none of the redundant chassis components has indicated any failures.
-A non-zero value specifies the faling component.
+A non-zero value specifies the failing component.
 .It 0x4
 Indicates the chassis battery charge is low.
 .It 0x2
@@ -245,10 +248,10 @@ argument.
 .\" TODO .It Fn pdc "PDC_CONF" "PDC_CONFIG_RECONF" "ptr" "hpa"
 .\" TODO .It Fn pdc "PDC_CONF" "PDC_CONFIG_INFO" "ptr" "hpa"
 .It Fn pdc "PDC_COPROC" "PDC_COPROC_DFLT" "ptr"
-Identify the coprocessors attached to CPU.
+Identify the coprocessors attached to the CPU.
 The
 .Ar ptr
-points to a memory location where data to be stored.
+points to a memory location where data is to be stored.
 The first word provides a mask for functional coprocessors and
 the second word is the mask for all present coprocessors.
 .It Fn pdc "PDC_DEBUG" "PDC_DEBUG_DFLT" "ptr"
@@ -259,28 +262,29 @@ argument.
 .\" TODO .It Fn pdc "PDC_INSTR" "PDC_INSTR_DFLT"
 .It Fn pdc "PDC_IODC" "PDC_IODC_READ" "ptr" "hpa" "entry" "addr" "count"
 Given a module
-.Ar hpa
-retrieve specified
+.Ar hpa ,
+retrieve the specified
 .Ar entry
-from module's IODC into a memory area at
+from the module's IODC into a memory area at
 .Ar adr
 of
-.At count
+.Ar count
 bytes long at most.
-.Ar Entry
-index is a one-byte index with value of zero being a special case.
-For the 0th entry an IODC header of 16 bytes long is returned instead
+The
+.Ar entry
+index is a one-byte index, with a value of zero being a special case.
+For the 0th entry, an IODC header of 16 bytes is returned instead
 of an actual code.
 .It Fn pdc "PDC_IODC" "PDC_IODC_NINIT" "ptr" "hpa" "spa"
 Non-destructively intialize the memory module specified by the
 .Ar hpa
 and
 .Ar spa
-arguments and return module status after the init in the first word
+arguments and return the module status after the init in the first word
 pointed to by the
 .Ar ptr
-argument futher following by the SPA space size and an amount of
-available memory bytes in subsequent two words.
+argument, followed by the SPA space size and an amount of
+available memory bytes in the subsequent two words.
 .It Fn pdc "PDC_IODC" "PDC_IODC_DINIT" "ptr" "hpa" "spa"
 Same as
 .Nm PDC_IODC_NINIT
@@ -289,20 +293,20 @@ except a destructive memory test is performed.
 For the memory module that is specified by
 .Ar hpa
 and
-.Ar spa
+.Ar spa ,
 return the last most severe error information comprised of copies of
-IO_STATUS, IO_ERR_RESP, IO_ERR_INFO, IO_ERR_REQ registers placed
+IO_STATUS, IO_ERR_RESP, IO_ERR_INFO, and IO_ERR_REQ registers placed
 into the data area pointed to by the
 .Ar ptr
-argument and clear the error status.
+argument, and clear the error status.
 .It Fn pdc "PDC_IODC" "PDC_IODC_IMEMMASTER" "ptr" "hpa"
-HPA for the primary memory module is returned in a owrd pointed to by the
+HPA for the primary memory module is returned in a word pointed to by the
 .Ar ptr
 argument for a memory module specified by
 .Ar hpa
 if it's configured as a slave module in an interleave group.
 .It Fn pdc "PDC_LAN_STATION_ID" "PDC_LAN_STATION_ID_READ" "macptr" "hpa"
-Retrieve the MAC address for the deviceat
+Retrieve the MAC address for the device at
 .Ar hpa
 into the data area pointed to by the
 .Ar macptr
@@ -336,7 +340,7 @@ the
 .Ar ptr
 argument.
 .It Fn pdc "PDC_MODEL" "PDC_MODEL_MODEL" "ptr" "os_id" "mod_addr"
-Return a string of 80 chars maximum stored at adress
+Return a string of 80 chars maximum stored at address
 .Ar mod_addr
 and conforming to the OS specified by the
 .Ar os_id
@@ -349,18 +353,18 @@ address receives the result string length.
 .\" TODO .It Fn pdc "PDC_MODEL" "PDC_MODEL_ENSPEC" "ptr"
 .\" TODO .It Fn pdc "PDC_MODEL" "PDC_MODEL_DISPEC" "ptr"
 .It Fn pdc "PDC_MODEL" "PDC_MODEL_CPUID" "ptr"
-Retrieve CPU mdel information.
+Retrieve CPU model information.
 A word stored at the address given by the
 .Ar ptr
-argument specifies CPU revision in the lower 5 bits followed by 7 bits
+argument specifies the CPU revision in the lower 5 bits followed by 7 bits
 of CPU model number.
 .It Fn pdc "PDC_MODEL" "PDC_MODEL_CPBALITIES" "ptr"
 Retrieve platform capabilities into the word pointed by the
 .Ar ptr
 argument.
-Bit 0 and one set specify that 64-bit and 32-bit OS is supported respectively.
+Bit 0 and 1 specify that a 64- or 32-bit OS is supported, respectively.
 .It Fn pdc "PDC_MODEL" "PDC_MODEL_GETBOOTOPTS" "ptr"
-Retrieve currently enabled, overall supported and enabled by default
+Retrieve the currently enabled, overall supported, and enabled by default
 boot test masks respectively stored at location pointed to by
 the
 .Ar ptr
@@ -372,7 +376,7 @@ argument and enable
 boot tests specified by the mask given in the
 .Ar enable
 argument.
-Memory location pointed to by the
+The memory location pointed to by
 .Ar ptr
 will contain the resulting masks as returned
 by the PDC_MODEL_GETBOOTOPTS function.
@@ -387,9 +391,9 @@ argument of no more than
 .Ar count
 bytes.
 .Pp
-Format of the NVM is as follows:
+The format of the NVM is as follows:
 .Bl -column "0x0000" "size" "contents" -offset left
-.It "offset" Ta "size" Ta "contents"
+.It Sy "offset" Ta Sy "size" Ta Sy "contents"
 .It "0x00" Ta "0x24" Ta "HV dependent"
 .It "0x24" Ta "0x20" Ta "bootpath"
 .It "0x44" Ta "0x04" Ta "ISL revision"
@@ -407,7 +411,7 @@ bytes at
 .Ar address
 in the NVM.
 .It Fn pdc "PDC_NVM" "PDC_NVM_SIZE" "ptr"
-Put the size of Non-Volatile Memory Into the word pointed to by the
+Put the size of Non-Volatile Memory into the word pointed to by the
 .Ar ptr
 argument.
 .It Fn pdc "PDC_NVM" "PDC_NVM_VRFY"
@@ -415,21 +419,21 @@ Verify that the contents of NVM are valid.
 .It Fn pdc "PDC_NVM" "PDC_NVM_INIT"
 Reset the contents of NVM to zeroes without any arguments.
 .It Fn pdc "PDC_HPA" "PDC_HPA_DFLT" "ptr"
-The return data provides the monarch CPUs HPA in the word pointed to by the
+The data returned provides the monarch CPUs HPA in the word pointed to by
 .Ar ptr .
 .It Fn pdc "PDC_HPA" "PDC_HPA_MODULES" "ptr"
 Retrieve the bit mask for devices on the CPU bus into the data location
-pointed to by the
+pointed to by
 .Ar ptr .
-First word is a bitmask for devices 0-31 and the second word is
-a bitmask for devices 32-63 where bits set to one specify that
-corresponding device number is on the same bus as the CPU.
+The first word is a bitmask for devices 0-31, and the second is
+a bitmask for devices 32-63, where bits set to one specify that
+the corresponding device number is on the same bus as the CPU.
 .\" TODO .It Fn pdc "PDC_PAT_IO" "PDC_PAT_IO_GET_PCI_RTSZ"
 .\" TODO .It Fn pdc "PDC_PAT_IO" "PDC_PAT_IO_GET_PCI_RT"
 .It Fn pdc "PDC_PIM" "PDC_PIM_HPMC" "offset" "ptr" "count"
 Get HPMC data from
 .Ar offset
-in Processor Internal Memory (PIM) into
+in Processor Internal Memory (PIM) into a
 .Ar ptr
 memory area of no more than
 .Ar count
@@ -437,28 +441,28 @@ bytes in size.
 Data provided includes (in the order it is copied into the buffer):
 general registers (r0-r31), control registers (cr0-cr31), space
 registers (sr0-sr7), IIA space tail, IIA offset tail, check type,
-cpu state, cache check, tlb check, bus check, assist check, assist
+CPU state, cache check, TLB check, bus check, assist check, assist
 state, path info, system responder address, system requestor address,
 FPU registers (fpr0-fpr31).
 .It Fn pdc "PDC_PIM" "PDC_PIM_SIZE" "ptr"
-Return the amount of data available in bytes in the word pointed to by the
+Return the amount of data available in bytes in the word pointed to by
 .Ar ptr .
 .It Fn pdc "PDC_PIM" "PDC_PIM_LPMC" "offset" "ptr" "count"
 Get LPMC data from
 .Ar offset
-in PIM into
+in PIM into a
 .Ar ptr
 memory area of no more than
 .Ar count
 bytes in size.
 Data provided includes: HV dependent 0x4a words, check type, HV dependent
-word, cache check, tlb, check, bus, check, assist check, assist state,
+word, cache check, TLB check, bus check, assist check, assist state,
 path info, system responder address, system requestor address,
 FPU registers (fpr0-fpr31).
 .It Fn pdc "PDC_PIM" "PDC_PIM_SBD" "offset" "ptr" "count"
 Get Soft Boot Data from
 .Ar offset
-in PIM into
+in PIM into a
 .Ar ptr
 memory area of no more than
 .Ar count
@@ -469,7 +473,7 @@ HV dependent word, CPU state.
 .It Fn pdc "PDC_PIM" "PDC_PIM_TOC" "offset" "ptr" "count"
 Get TOC (Transfer Of Control) data from
 .Ar offset
-in PIM into
+in PIM into a
 .Ar ptr
 memory area of no more than
 .Ar count
@@ -479,14 +483,15 @@ Data provided includes: general registers (r0-r31), control registers
 HV dependent word, CPU state.
 .It Fn pdc "PDC_POW_FAIL" "PDC_POW_FAIL_DFLT"
 Prepare for power fail.
-On the machines that provide power failure interrupts this function is
-to be called after the operating system has completed shutdown to 
-finish system dependent tasks and power down.
+On the machines that provide power failure interrupts, this function is
+to be called after the operating system has completed
+.Xr shutdown 8
+to finish system-dependent tasks and power down.
 This function only requires 512 bytes of stack.
 .It Fn pdc "PDC_PROC" "PDC_PROC_STOP"
-Stop currently executing processor and also disable bus requestorship,
-disable interrupts and exclude processor from cache coherency protocols.
-Caller must flush any necessary data from cache before calling this
+Stop the currently executing processor and also disable bus requestorship,
+disable interrupts, and exclude the processor from cache coherency protocols.
+The caller must flush any necessary data from the cache before calling this
 function.
 .It Fn pdc "PDC_PROC" "PDC_PROC_RENDEZVOUS"
 Enter the reset rendezvous code on the current processor.
@@ -497,6 +502,7 @@ Get the mask of default bits implemented into a word pointed to by the
 .Ar ptr
 argument.
 The following mask values are possible:
+.Pp
 .Bl -tag -width 100 -compact
 .It 1
 Default endianess bit is available.
@@ -518,8 +524,8 @@ register address into the word pointed to by the
 argument.
 Bit-0 in the
 .Dq power
-register address being set spcifies the power button being depressed.
-No dampenning is required as opposed to
+register address being set specifies the power button being depressed.
+No dampening is required, unlike with the
 .Xr lasi 4
 power circuit.
 .It Fn pdc "PDC_SOFT_POWER" "PDC_SOFT_POWER_ENABLE" "ptr" "stat"
@@ -527,7 +533,8 @@ Enable (zero
 .Ar stat )
 or disable (non-zero
 .Ar stat )
-soft power function where disable means the mashine will turn immidiately off
+the soft power function,
+where disable means the machine will turn immediately off
 should the power get depressed.
 The
 .Ar ptr
@@ -544,9 +551,9 @@ argument of no more than
 .Ar count
 bytes.
 .Pp
-Format of the stable storage is as follows:
+The format of the stable storage is as follows:
 .Bl -column "offset" "0x00" "contents" -offset left
-.It "offset" "size" "contents"
+.It Sy "offset" "size" "contents"
 .It "0x0000" "0x20" "primary bootpath"
 .It "0x0020" "0x20" "reserved"
 .It "0x0040" "0x02" "OS ID"
@@ -566,7 +573,7 @@ The
 .Dq OS ID
 field may have the following values:
 .Bl -column "value" "OS" -offset left
-.It "value" "OS"
+.It Sy "value" "OS"
 .It "0x000" "No OS-dependent info"
 .It "0x001" "HP-UX"
 .It "0x002" "MPE-iX"
@@ -606,21 +613,21 @@ to zeroes.
 .It Fn pdc "PDC_SYSMAP" "PDC_SYSMAP_FIND" "ptr" "path" "number"
 Map module
 .Ar number
-into HPA and also provide area size starting at HPA and number of
+into HPA and also provide an area size starting at HPA and a number of
 additional addresses placed into the data area pointed to by the
 .Ar ptr
-argument words one, two and three respectively.
-Device path is placed into data area pointed to by the
+argument words one, two, and three, respectively.
+The device path is placed into the data area pointed to by the
 .Ar path
 argument.
 .It Fn pdc "PDC_SYSMAP" "PDC_SYSMAP_ADDR" "ptr" "im" "ia"
-Retrieve list of additional addresses for the module number
+Retrieve a list of additional addresses for the module number
 .Ar im
 for the address index
 .Ar ia .
-Result is placed into the data area pointed to by the
-.Ar ptr
-where first word gives the address and second the size of the area.
+The result is placed into the data area pointed to by
+.Ar ptr ,
+where the first word gives the address and the second the size of the area.
 .It Fn pdc "PDC_SYSMAP" "PDC_SYSMAP_HPA" "ptr" "path_ptr"
 Map device
 .Ar path_ptr
@@ -629,21 +636,23 @@ into device's HPA placed into a word pointed to by the
 argument.
 .It Fn pdc "PDC_TLB" "PDC_TLB_INFO" "ptr"
 Retrieve the hardware TLB handler parameters.
-This includes minimal and maximal size for the page table in bytes stored
-into words zero and one respectively in the data area pointed to by the
+This includes a minimal and maximal size for the page table, in bytes,
+stored into words zero and one, respectively,
+in the data area pointed to by the
 .Ar ptr
 argument.
 .It Fn pdc "PDC_TLB" "PDC_TLB_CONFIG" "ptr" "base" "size" "param"
-Configure hardware TLB miss handler given same parameters fetched
-previously with PDC_TLB_INFO into data are pointed to by the
+Configure the hardware TLB miss handler given the same parameters fetched
+previously with PDC_TLB_INFO into data area pointed to by the
 .Ar ptr
 and page table
 .Ar base
 address, page table
-.Ar size
+.Ar size ,
 and handler parameters
 .Ar param .
-Hardware TLB handler parameter bits:
+The hardware TLB handler parameter bits are as follows:
+.Pp
 .Bl -tag -width 0xff -compact
 .It 1
 Enable the hardware TLB miss handler.
@@ -653,12 +662,13 @@ Pointer to the next page table entry is put into cr28.
 .It 6
 Next pointer field of the page table entry is put into cr28.
 .El
-Resetting page table address and/or size without disabling
-hardware TLB miss handler is allowed.
-Any changes made are immidiate upon Code or Data virtual
+.Pp
+Resetting the page table address and/or size without disabling
+the hardware TLB miss handler is allowed.
+Any changes made are immediate upon Code or Data virtual
 address translation bits are set in PSW.
 .It Fn pdc "PDC_TOD" "PDC_TOD_READ" "ptr"
-Read the TOD which is a UNIX Epoch time into the data area
+Read the TOD, which is a UNIX Epoch time, into the data area
 pointed to by the
 .Ar ptr
 argument.
@@ -671,13 +681,22 @@ seconds and
 .Ar usec
 microseconds.
 .It Fn pdc "PDC_TOD" "PDC_TOD_ITIMER" "ptr"
-Get TOD and CPU timer accuracy into data location pointed to by the
+Get TOD and CPU timer accuracy into the data location pointed to by the
 .Ar ptr
 argument.
-First two words spcify a double floating-point value giving
+The first two words specify a double floating-point value giving
 CPU timer frequency.
-Next two words provide accuracy in parts per billion for the TOD and
-CPU timer respectively.
+The next two words provide accuracy in parts per billion for the TOD and
+CPU timer, respectively.
+.El
+.Sh FILES
+.Bl -tag -width /sys/arch/hppa/dev/cpudevs -compact
+.It machine/pdc.h
+C header file with relevant definitions.
+.It /sys/arch/hppa/dev/cpudevs
+System components' version numbers.
+.It /dev/console
+System console device.
 .El
 .Sh DIAGNOSTICS
 Upon successfull completion all procedures return zero.
@@ -697,15 +716,6 @@ Invalid argument
 .It PDC_ERR_PFAIL
 Aborted by powerfail
 .El
-.Sh FILES
-.Bl -tag -width /sys/arch/hppa/dev/cpudevs -compact
-.It machine/pdc.h
-C header file with relevant definitions.
-.It /sys/arch/hppa/dev/cpudevs
-System components version numbers.
-.It /dev/console
-System console device.
-.El
 .Sh SEE ALSO
 .Xr intro 4 ,
 .Xr io 4 ,