Re: Quick PCI Tutorial (WAS: Documenting Source Code)

[George Mena <George -dot- Mena -at- ESSTECH -dot- COM>]

What Mysore Dattatreya and others tasked with hardware documentation
responsibilities need is to have a copy of the PCI Local Bus
Specification, Rev. 2.1, available as a reference document when writing
PCI-based hardware documentation.

PERR# refers to the Parity Error bus operation commonly found in
PCI-based computer systems.

The description Mysore is trying to deal with is plagiarized directly
from Section 3.8.2.1 of the PCI Local Bus Spec, pp 98-99.  One of the
engineers Mysore is dealing with developed the input from the spec.  In
part the plagiarized section actually reads as follows:
===================
An agent must always assert PERR# two clocks after a data transfer in
which an error occurred, as shown in Figure 3-26....  Once PERR# is
asserted, it must remain asserted until two clocks following the actual
transfer.  A master knows a data parity error occurred anytime PERR# is
asserted but only knows the transfer was error free two clocks following
the transfer
====================

To understand parity generation and detection in the PCI world, please
read on.

Following are key excerpts from pp. 95-99 of the PCI Local Bus spec,
sections 3.8, 3.8.1, 3.8.2 and 3.8.2.1:
===================
Section 3.8 (partial):

PCI provides for parity and other systems errors to be reported.... The
discussion of errors is divided into the following two sections covering
parity generation and detection, and error reporting.

Section 3.8.1 (partial):

Parity on PCI provides a mechanism to determine transaction by
transaction if the master is successful in addressing the desired target
and if data transfers correctly between them.

Section 3.8.2 (partial)

Since it is generally not possible to associate system errors with a
specific access chain, they are reported directly to the system level.
Two signals (pins) are used in the PCI error reporting scheme.  PERR# is
used exclusively for reporting data parity errors on all transactions
except Special Cycle commands.  PERR# is a sustained tri-state signal
tri-state signal that is bused to all PCI agents.  Bus protocol assures
that PERR# will never be simultaneously driven by multiple bus agents
and that proper signal turn around times are observed to avoid any
driver contention.

Section 3.8.2.1 (partial)

PCI uses the PERR# pin to signal a data parity error between the current
master and target on PCI (except on Special Cycle commands).  Only the
master of a corrupted data transfer is allowed to report parity errors
to software, using mechanisms other than PERR# (i.e., requesting an
interrupt or asserting SERR#).  On a write transaction, the target
always signals data parity errors back to the master on PERR#.  On a
read transaction, the master asserts PERR# to indicate to the system
that an error was detected.  In both cases, this gives the originator of
the access, at each hardware or software level, the prerogative of
recovery.

An agent must always assert PERR# two clocks after a data transfer in
which an error occurred, as shown in Figure 3-26....  Once PERR# is
asserted, it must remain asserted until two clocks following the actual
transfer.  A master knows a data parity error occurred anytime PERR# is
asserted but only knows the transfer was error free two clocks following
the transfer....Since PERR# is a sustained tri-state signal, it must be
actively driven to the correct value on each qualified edge.  To return
it to nominal state at the end of each bus operation, it must be
actively driven high for one clock period, starting two clocks after the
AD bus turnaround cycle (e.g., clock 7 in Figure 3-26).  PERR# may never
be driven (enabled) for the current cycle until at least three clocks
after the address phase (SAC or DAC).
===================

Industry standard plagiarism is at work here from the engineering side
of the house.  In this case, since Mysore apparently doesn't have a copy
of the Local Bus Spec, I believe an engineer tried to simplify the
definition of PERR# for the writer's benefit.  As perhaps too many tech
writers don't necessarily understand either ISA or PCI bus operations at
the hardware level, the engineer, as the subject matter expert, rewrote
and simplified the explanation of the PERR# operation so that the writer
could understand it.

Mysore's question on making the engineer's description of PERR# more
readable is a potentially dangerous one because it erroneously assumes
that a *style guide* would have a better way of describing this.  If the
writer has a copy of the PCI Local Bus Spec and *reads it*, however, it
soon becomes apparent that trying to minimize this plagiarized
description even further is ill-advised because anything that would be
written in even fewer words would be technically wrong!  This is where a
tech writer directly benefits from getting some hardcore engineering
classes under the belt.  The knowledge acquired from these classes
become vital and critical.

To discount this message is equivalent to committing professional
suicide where your career is concerned.

To order the PCI Local Bus Specification, contact:

PCI Special Interest Group
P.O. Box 14070
Portland, OR U.S.A. 97214
800-433-5177 (USA)
503-797-4207 (International)
503-234-6762 (FAX)
http://www.pcisig.org
Compuserve:  GO PCVENH

Additional reference book of note:

PCI System Architecture, 3rd edition
Tom Shanley and Don Anderson/MindShare Inc.
The PC System Architecture Series
Addison-Wesley, ISBN 0-201-40993-3
$36.95 US/$50.95 Canada

(available locally in Silicon Valley at Computer Literacy, North First
St. & Trimble Rd., San Jose, CA)

George

> -----Original Message-----
> From: Mysore S Dattatreya [SMTP:datta -at- WIPINFO -dot- SOFT -dot- NET]
> Sent: Tuesday, July 28, 1998 8:32 AM
> To:   TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject:      Documenting Source Code
>
> Dear Techwhirlers,
>
        [George Mena]  snip
> I have yet another question on documenting for hardware projects.
> These projects
> involve documenting codes written in Verilog and other high level
> languages specific
> to ASICs.  My question is pertaining to an example which I shall
> quote:
>
> This is the description of a signal and it is as below:
>
> "The PERR# pin is sustained tri-state and is driven active by the
> agent receiving
> data two clocks following the data when a data parity error is
> detected."
>
> Is there any way that this can be made readable and simpler?  Are
> there any style
> guides avaiable whilst documenting such information?  There are many
> such instances
> and surprisingly these are part of the IEEE specifications.  I am not
> aware if this is
> the method followed while documenting signal descriptions.  Correct me
> if I am wrong.
> I am badly in need of some direction.  Can someone help me out?
>
> Thanks for the help and expecting tonnes of information, suggestions
> and advice
> on this score.
>
>