Monday, November 9, 2009

32.1. External Documentation










 < Free Open Study > 







32.1. External Documentation



Documentation on a software project consists of information both inside the sourcecode listings and outside them�usually in the form of separate documents or unit development folders. On large, formal projects, most of the documentation is outside the source code (Jones 1998). External construction documentation tends to be at a high level compared to the code, at a low level compared to the documentation from the problem definition, requirements, and architecture activities.



Cross-Reference





For more on external documentation, see Section 32.6, "IEEE Standards."




Unit development folders A unit-development folder (UDF), or software-development folder (SDF), is an informal document that contains notes used by a developer during construction. A "unit" is loosely defined, usually to mean a class, although it could also mean a package or a component. The main purpose of a UDF is to provide a trail of design decisions that aren't documented elsewhere. Many projects have standards that specify the minimum content of a UDF, such as copies of the relevant requirements, the parts of the top-level design the unit implements, a copy of the development standards, a current code listing, and design notes from the unit's developer. Sometimes the customer requires a software developer to deliver the project's UDFs; often they are for internal use only.



Further Reading





For a detailed description, see "The Unit Development Folder (UDF): An Effective Management Tool for Software Development" (Ingrassia 1976) or "The Unit Development Folder (UDF): A Ten-Year Perspective" (Ingrassia 1987).




Detailed-design document The detailed-design document is the low-level design document. It describes the class-level or routine-level design decisions, the alternatives that were considered, and the reasons for selecting the approaches that were selected. Sometimes this information is contained in a formal document. In such cases, detailed design is usually considered to be separate from construction. Sometimes it consists mainly of developers' notes collected into a UDF. And sometimes� often�it exists only in the code itself.












     < Free Open Study > 



    Robbing Acme Fashions, Inc.





    Robbing Acme
    Fashions, Inc.



    ACME Fashions, Inc., established itself as a
    clothing and apparel retailer operating through outlet stores in shopping malls
    across the country. A central warehouse supplied goods to its stores. Acme
    Fashions also sold its goods directly to customers through catalogs and orders
    taken over the telephone. In the early 1990s, Acme Fashions installed an Oracle
    database inventory management and shipment tracking system that enabled the
    company to expand considerably.



    In the mid 1990s, as the Web gained
    popularity, Acme's vice president of marketing decided to post its catalog on
    its Web site at http://www.acme-fashions.com. The marketing team busily began
    writing HTML pages and soon converted the catalog to electronic form. A few
    months after putting up the Web site, the sales volume tripled. The marketing
    vice president went on to become Acme Fashions, Inc.'s CEO. The company had
    taken its first step toward becoming an electronic storefront.



    Setting Up Acme's Electronic Storefront



    In 1999, Acme Fashions, Inc., decided to open
    its doors to the world by hosting its business on the World Wide Web. Management
    wanted to debut the Web site in time to cash in on the 2000 holiday season.
    As
    the deadline rapidly approached, management decided to outsource development of
    its electronic storefront to a consulting company specializing in e-commerce
    software development.



    The consultant and an in-house team worked day and night to
    open on November 1, 2000. They chose to integrate the existing Web-based
    catalog operation with a commercially available shopping cart system. They
    finally were able to tie up all the remaining loose ends and get the system up
    and running. The completed system is shown in style='color:#003399'>Figure 10-4.



    style='font-size:10.5pt;font-family:Arial'>Figure 10-4. Acme Fashions, Inc.'s
    electronic storefront




    However, as sales from the Web site picked up, so too did
    complaints. Most of the complaints were traced to the accounting department and
    the warehouse inventory department. The accounting department received frequent
    complaints of products being sold at lower than posted prices, when no
    discounts or promotions had been offered. Shipping clerks frequently were puzzled
    when they received orders to ship quantities in negative numbers. Under
    tremendous pressure because of the holiday season, all the complaints were
    attributed to unexplained glitches and were written off. When the total written
    off ran to almost $100,000�and after weeks of trying to isolate the source of
    the problem�management called in a team of application security assessment
    experts.



    Tracking
    Down the Problem



    Acme's Web storefront�www.acme-fashions.com�had been implemented
    with the following technologies:



    style='width:100.0%'>























    Operating system



    Microsoft Windows NT 4.0



    Web server



    Microsoft Internet Information Server (IIS) 4.0



    Online catalog



    Template and Active Server Pages (ASP)



    Back-end database



    Microsoft Access 2.0



    ShoppingCart



    Shopcart.exe




    The HTML catalog was written by using templates and Active
    Server Pages. The marketing team had used a FoxPro database to generate HTML pages
    automatically for the catalog. It was then converted to a Microsoft Access
    database and interfaced with ASP. A shopping cart application, ShopCart.exe,
    was set up on the Web server, and the ASP templates were designed to generate
    HTML with links to the shopping cart application. The shopping cart picked up
    the product information from the generated HTML. At the time, it seemed to be
    the easiest and fastest way of getting the electronic storefront up and running
    before the deadline.



    ShopCart.exe had its own session management system, which
    relies on cookies and server-side session identifiers to maintain the shopping
    cart sessions. Because modification of ShopCart.exe wasn't possible, the task
    of validating proper inputs was pushed out to the JavaScript running on the
    customers' browsers.



    The application security assessment team started looking at
    all possible entry and attack points. After examining the application and the
    way the Web site worked, the team uncovered some interesting security errors.



    The
    Hidden Dangers of Hidden Fields


    The security team found a major loophole in the way the
    shopping cart system was implemented. The only way to associate price with a
    product was via hidden tags within HTML pages. style='color:#003399'>Figure 10-5 shows a page featuring shirts from
    the catalog at http://www.acme-fashions.com/.



    style='font-size:10.5pt;font-family:Arial'>Figure 10-5. Catalog page from
    www.acme-fashions.com




    Each shirt had an associated form that accepted the quantity
    of shirts desired and a link to place them in the shopping cart. Looking at the
    HTML source code, shown in style='color:#003399'>Figure 10-6, the team discovered that the
    vulnerability lay in the last few lines of the HTML code.



    style='font-size:10.5pt;font-family:Arial'>Figure 10-6. HTML source code of the
    catalog page




    The following source code had been used to invoke
    ShopCart.exe:



    01: <form method=post action="/cgi-bin/shopcart.exe/MYSTORE-AddItem">
    02: <input type=hidden name="PartNo" value="OS0015">
    03: <input type=hidden name="Item" value="Acme Shirts">
    04: <input type=hidden name="Price" value="89.99">
    05: Quantity: <input type=text name=qty value="1" size=3
    06: onChange="validate(this);">
    07: <input type=image src='buy00000.gif' name='buy' border='0' alt='Add To
    08: Cart' width="61" height="17">
    09: </form>


    When the user clicked the Buy button, the browser submitted
    all the input fields to the server, using a POST request. Note the three hidden
    fields on lines 2, 3, and 4 of the code. Their values were sent along with the
    POST request. The system was thus open to an application-level vulnerability,
    because a user could manipulate the value of a hidden field before submitting
    the form.



    To understand this situation better, look at the exact HTTP
    request that goes from the browser to the server:



    POST /cgi-bin/shopcart.exe/MYSTORE-AddItem HTTP/1.0
    Referer: http://www.acme-fashions.com/shirtcatalog/shirts2.asp
    Connection: Keep-Alive
    User-Agent: Mozilla/4.76 [en] (Windows NT 5.0; U)
    Host: www.acme-fashions.com
    Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */*
    Accept-Encoding: gzip Accept-Language: en
    Accept-Charset: iso-8859-1,*,utf-8
    Cookie: ASPSESSIONIDQQGQQKIG=ONEHLGJCCDFHBDHCPKGANANH; shopcartstore=3009912
    Content-type: application/x-www-form-urlencoded
    Content-length: 65
     
    PartNo=OS0015&Item=Acme+Shirts&Price=89.99&qty=1&buy.x=16&buy.y=5


    The values of the hidden fields PartNo,
    Item, and Price
    are submitted in the POST request to /cgi-bin/shopcart.exe.
    That's the only way that ShopCart.exe learns the price of, for example, shirt
    number OS0015. The browser displays the response shown in style='color:#003399'>Figure 10-7.



    style='font-size:10.5pt;font-family:Arial'>Figure 10-7. Shopping cart contents




    If there was a way to send a POST request with a modified
    value in the Price field, the user could
    control the price of the shirt. The following POST request would get him that
    shirt for the low price of $0.99 instead of its original price of $89.99!



    POST /cgi-bin/shopcart.exe/MYSTORE-AddItem HTTP/1.0
    Referer: http://www.acme-fashions.com/shirtcatalog/shirts2.asp
    Connection: Keep-Alive
    User-Agent: Mozilla/4.76 [en] (Windows NT 5.0; U)
    Host: www.acme-fashions.com
    Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */*
    Accept-Encoding: gzip Accept-Language: en
    Accept-Charset: iso-8859-1,*,utf-8
    Cookie: ASPSESSIONIDQQGQQKIG=ONEHLGJCCDFHBDHCPKGANANH; shopcartstore=3009912
    Content-type: application/x-www-form-urlencoded
    Content-length: 64
     
    PartNo=OS0015&Item=Acme+Shirts&class=docemphstrong1>Price=0.99&qty=1&buy.x=16&buy.y=5


    An easy way of manipulating the price is to save the catalog
    page, shirts2.asp, viewed in the browser as a
    local copy, shirts2.html, to the user's hard disk,
    edit the saved file, and make the changes in the HTML code. style='color:#003399'>Figure 10-8 shows how the user saves the page.



    style='font-size:10.5pt;font-family:Arial'>Figure 10-8. Saving a local copy to
    the user's hard disk




    The user first changes the value of the class=docemphasis1>Price field in the line <INPUT
    type=hidden name="Price" value="89.99">.
    His
    second change is to fix the ACTION= link in the
    <FORM> tag so that it points to
    http://www.acme-fashions.com/cgi-bin/shopcart.exe. style='color:#003399'>Figure 10-9 shows shirts2.html after it was
    modified to change the price to $0.99.



    style='font-size:10.5pt;font-family:Arial'>Figure 10-9. The shirts.html file
    being modified to change the price




    Now if the user opens this modified file, class=docemphasis1>shirts2.html, in the browser and submits a request to
    buy the shirt, he sees the window shown in style='color:#003399'>Figure 10-10.



    style='font-size:10.5pt;font-family:Arial'>Figure 10-10. Results from tampering
    with the hidden field




    Is this a great way of going bargain shopping or what? As
    incredible as it seems, this indeed was the problem that accounted for Acme
    Fashions, Inc.'s loss of revenue. After a thorough reconciliation of orders and
    transactions, the application security assessment team found that numerous
    "customers" were able to buy items for ridiculously low prices. We
    say "customers" facetiously because they most likely were hackers.



    We alluded to the dangers of passing information in hidden
    fields in style='color:#003399'>Chapter 7 where we showed how to go about
    quickly sifting through source code to locate hidden fields. Hacking
    applications using information passed back and forth via hidden fields is a
    trivial task. It involves no special skills other than using a browser and
    perhaps fumbling around with Unix's Visual Editor (vi) or Microsoft Windows'
    NotePad application. Yet the effect is quite devastating.



    Bypassing
    Client-Side Validation



    The next error spotted by the security testing team was the
    way inputs were validated before being passed to ShopCart.exe. Web applications
    consist of many scripts and interactive components, which interact primarily
    with the user via HTML forms on browsers. The interactive part of any component
    takes input from the HTML form and processes it on the server. HTML forms are
    generic when it comes to capturing data, and there is no way to ensure
    validation of data within such forms. For example, if an HTML form is designed
    to accept a date, a user can enter a date such as 99/88/77 and the browser
    won't even care. The application has to have its own input validation
    mechanisms to filter out such erroneous inputs to ensure that the input complies
    with predetermined criteria for the application. Input validation for HTML
    forms can be done either on the server side with Perl, PHP, or ASP, among
    others, or on the client side, using scripting languages such as JavaScript or
    VBScript.



    style='width:90.0%'>




    style='font-size:16.5pt;font-family:Arial'>Using Search Engines to Look for
    Hidden Fields


    You can use any of the many Internet search engines to
    quickly check whether your Web site or application contains hidden fields.
    For example, style='color:#003399'>Figure 10-11 shows how to use Google to
    determine whether hidden fields are used to pass price information within
    www.acme-fashions.com.


    style='font-size:10.5pt;font-family:Arial'>Figure 10-11. A Google search


    Because www.acme-fashions.com is a popular shopping site,
    Google has cataloged it. style='color:#003399'>Figure 10-12 reveals the results of the
    search: all pages within the domain acme-fashions.com that contain the
    strings "type=hidden" and class=docemphasis1>"name=price." Be sure to restrict the
    search to the chosen site; otherwise you may end up having to sift through
    thousands of results!


    style='font-size:10.5pt;font-family:Arial'>Figure 10-12. Results of the
    Google search




    Acme's development team recognized the need for such input validation,
    but because ShopCart.exe was a prepackaged application that couldn't be
    modified to incorporate input validation. Hence the team decided to move the
    burden of input validation to client-side scripts running on the browser
    itself. Someone even remarked, "Yes, this is a good idea since it will
    save the server's CPU usage. Let the work be performed by the client's browser
    instead."



    The fact that any client-side mechanism could be altered by
    editing the HTML source code received by the browser was overlooked. The
    security testing team found several instances of client-side validation being
    used on www.acme-fashions.com. style='color:#003399'>Figure 10-13 shows client-side input
    validation in action on Acme's system. A user tries to buy "�5"
    shirts and an alert pops up stating that the user has entered an invalid
    number.



    style='font-size:10.5pt;font-family:Arial'>Figure 10-13. Client-side
    validation, using JavaScript




    The JavaScript code that validates the input is shown in style='color:#003399'>Figure 10-13. For the sake of clarity, the
    following is the code separated from the HTML elements:



    <script>
    function validate(e) {
    �� if(isNaN(e.value) || e.value <= 0) {
    ����� alert("Please enter a valid number");
    ����� e.value = 1;
    ����� e.focus();
    ����� return false;
    �� }
    �� else {
    ����� return true;
    �� }
    }
    </script>
    :
    :
    <input type=text name=qty value="1" size=3 onChange="validate(this);">


    This code ensures that only positive numbers are allowed in
    the field qty. But, because the validation is
    done by a client-side script, it is easy to bypass. Simply disabling the
    execution of JavaScript by setting the browser preferences allows an attacker
    to bypass client-side validation! If we choose to disable JavaScript, as shown
    in style='color:#003399'>Figure 10-14, we can enter whatever value we
    desire in the input fields.



    style='font-size:10.5pt;font-family:Arial'>Figure 10-14. Disabling JavaScript




    style='color:#003399'>Figure 10-14 shows the Disabling JavaScript in
    Netscape Now if a user were to send a quantity of "�3," the browser
    would issue the following POST request to the server:



    POST /cgi-bin/shopcart.exe/MYSTORE-AddItem HTTP/1.0
    Referer: http://www.acme-fashions.com/shirtcatalog/shirts2.asp
    Connection: Keep-Alive
    User-Agent: Mozilla/4.76 [en] (Windows NT 5.0; U)
    Host: www.acme-fashions.com
    Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */*
    Accept-Encoding: gzip Accept-Language: en
    Accept-Charset: iso-8859-1,*,utf-8
    Cookie: ASPSESSIONIDQQGQQKIG=ONEHLGJCCDFHBDHCPKGANANH; shopcartstore=3009912
    Content-type: application/x-www-form-urlencoded
    Content-length: 63
     
    PartNo=OS0015&Item=Acme+Shirts&Price=-3&qty=1&buy.x=16&buy.y=5


    Note how this HTTP request completely bypasses client-side
    validation. style='color:#003399'>Figure 10-15 shows the server's response.



    style='font-size:10.5pt;font-family:Arial'>Figure 10-15. Purchasing a negative
    number of shirts




    The screenshot shows that the user has placed
    one order for 5 shirts at $54.99 each and another order for �3 shirts at $89.99
    each. The total bill comes is $4.98. The ability to place orders for negative
    numbers to reduce the total amount of the bill would make shoppers quite happy!
    This flaw is what caused the shipping clerks at Acme to receive orders for
    negative numbers of items.



    Acme Fashions, Inc.'s management concluded
    that client-side input validation is dangerous and should not be used. Who is
    to blame? The flaw lies with the way ShopCart.exe was designed in the first
    place. The onus of validating inputs should be on the ShopCart.exe application.
    But, because it had no input validation, the Web site development team was
    forced to resort to client-side validation.



    Even today, many third-party commercial
    shopping cart systems lack proper input validation. Sometimes it is possible to
    place orders for fractional quantities. At other times it even is possible to
    insert meta-characters or arbitrarily long buffers and crash the server-side
    application.



     





    HyperTransport Configuration Space Format



    [ Team LiB ]









    HyperTransport Configuration Space Format


    This section describes the general format of the configuration space used by a HyperTransport functional device. The discussion here focuses on two major areas:



    • How a HyperTransport device is similar and different from a PCI device in its use of the generic header region of configuration space.


    • The use of the required and optional HyperTransport advanced capability register blocks also located in the required 256 byte configuration space.



    Two Header Formats Are Used


    The first one fourth (16 dwords) of any PCI configuration space is called the header. As in the case of PCI devices, HyperTransport devices use two header formats: one for HT-to-HT bridges, called header type 1, and the other for all non-bridge devices (including tunnels and single link end (cave) devices) called header type 0. The lower bits in the Header Type field within both types of PCI configuration header is hard coded with the type code; software checks this field early in the process of device discovery to determine which of the header formats it is dealing with.


    This chapter covers the format of HyperTransport header type 0 (non-bridges); refer to "HyperTransport Bridge Header Fields" on page 409 for a description of type 1 (HT-to-HT bridge) headers.



    The Type 0 Header Format


    Figure 13-7 on page 322 depicts the format of the type 0 (non HT-to-HT bridge) header. Basic PCI functionality is managed by having BIOS or other low level software read certain hard-coded header fields to obtain device requirements, then having it program other fields to set up plug-and-play options.


    Figure 13-7. PCI Type 0 Configuration Space Header



    Again, note that the well-defined PCI configuration space header only occupies the first one-fourth (16 dwords) of configuration space.



    PCI Advanced Capability Registers


    While many early PCI devices were managed using just the register fields in the configuration space header, many additional features have been added over the years which require dedicated registers to manage them. For these devices which have capabilities beyond basic PCI compliance, the generic PCI header registers are augmented by one or more additional register sets outside of the header area, but still within the 256 byte PCI configuration space. PCI calls these advanced capability register blocks; refer to Figure 13-8 on page 323.


    Figure 13-8. PCI Configuration Space With Advanced Capability Register Block(s)



    Many Advanced Capabilities Are Defined

    Under the current PCI specification, advanced capability block register sets have been defined for all sorts of purposes. Two important classes are:



    • Register sets for bus extensions such as HyperTransport, PCI-X, and AGP.


    • Register sets for enhanced device management, including Message Signalled Interrupts (MSI), Power Management, Vital Product Data, etc.



    When a PCI compatible device is designed, the basic PCI configuration space type 0 or type 1 header fields are implemented as are any additional advanced capability register blocks which may be needed. The format of an advanced capability block varies with the type, and a Capability ID byte at the start of each block identifies which type it is; the capability ID for HyperTransport is 08. At a minimum, a HyperTransport device must implement the 256 byte PCI configuration space memory, containing a header AND at least one HyperTransport advanced capability block (Host/Secondary or Slave/Primary Interface Block).



    Discovering The Advanced Capability Blocks

    If a PCI compatible device implements advanced capability blocks, low-level software must find and configure each one. Because the specific location of advanced capability blocks within the 256 byte configuration space is not specified, they must be "discovered" by executing some variation of the following software configuration process (Refer to Figure 13-8 on page 323):









    1. Use the capability pointer (CapPtr) at dword 13 in the header to determine the configuration space offset (from the beginning of configuration space) to the first advanced capability register block. Check the first byte in the block to determine the capability ID (HT = 08).



    2. Next, check the upper byte in the first dword to determine the HyperTransport capability block Type. HyperTransport supports a number of these: Host/Secondary, Slave/Primary, Interrupt Discovery & Configuration, etc.



    3. Set up all of the registers in the capability block using configuration cycles.



    4. Use the next pointer (NPtr) contained in the second byte of the first advanced capability block to determine the offset (from the beginning of configuration space) to the next capability block in the "linked list". If the ID field is "08", this is another HyperTransport capability block. Read the Type field, and set up the register fields as appropriate.



    5. Continue the discovery and set up process until the last capability block has been located and set up. If a block is the last one, its Nptr field is zero � indicating the end of the linked list of advanced capability blocks.



    Refer to MindShare's PCI System Architecture, 4th Ed. book for a complete description of configuration space advanced capability management.




    HyperTransport Configuration Type 0 Header Fields


    In this section, the configuration header format for non-bridge HyperTransport devices (type 0 header format) is described. For the most part, HyperTransport devices use these fields in the same way as PCI devices; the few differences are described here. Header fields not mentioned are used in the same way as in PCI devices. Refer to "HyperTransport Bridge Header Fields" on page 409 for a description of HyperTransport bridge headers.


    Header Command Register

    As shown in Figure 13-9, the command register occupies the lower 16 bits at dword 01. The header Command register is used by BIOS or other software to enable basic capabilities of the device on the primary bus, including bus mastering, target address decoding, error response capability, etc. Refer to Table 13-1 for bit definitions; bits marked "0" are tied low.


    Figure 13-9. HyperTransport Technology Header Command Register Usage
































    Table 13-1. HyperTransport Header Command Register Bit Assignment

    Bit



    Function



    0



    I/O Space.
    When this bit is set to a one, the device may act as a target of requests in the I/O portion of the HyperTransport memory map. If this is a subtractive decoder, the setting of this bit does not affect device's ability to claim requests with Compat bit set. Warm Reset to 0.



    1



    Memory Space.
    When this bit is set to a one, the device may act as a target of requests in the Memory portion of the HyperTransport memory map. If this is a subtractive decoder, the setting of this bit does not affect device's ability to claim requests with Compat bit set. Warm Reset to 0.



    2



    Bus Master.
    When set to a one, enables the device to issue memory or I/O (range) requests onto its HyperTransport chain. State of bit does not affect ability to forward requests on behalf of other devices. Warm Reset to 0.



    8



    SERR# Enable.
    When set a one, the device will flood all outgoing links with sync packets in the event of an error which has been programmed to cause a sync flood. If this bit is clear, device only generates sync packets as a part of initial link synchronization. Bit does not affect device's ability to propagate sync packets from one link to another in a chain. Note: sync flood is similiar to SERR# assertion in PCI. Warm Reset to 0.



    Other Bits



    All other Header Command Register bits are unused in HyperTransport, and should be tied to a low level.




    HeaderStatus Register

    As shown in Figure 13-10 on page 327, the status register occupies the upper 16 bits at dword 01. The HyperTransport device header Status register is used by BIOS or other software to read basic capabilities and dynamic status (e.g. PCI error events) associated with the device's primary bus. As in the case of the header Command register, a number of these bits are used differently than PCI, or not at all. Refer to Table 13-2 on page 328 for bit definitions


    Figure 13-10. HyperTransport Technology Header Status Register Usage




































    Table 13-2. HyperTransport Header Status Register Bit Assignment

    Bit



    Function



    4



    Capabilities List.
    (Introduced in the PCI 2.2 Specification) When this bit is hardcoded to a one, the device indicates there are one or more advanced capability block register sets to be discovered. All HyperTransport devices are required to have at least one advanced capability block (to support HyperTransport), so this bit is always set = 1. When software reads this bit high, it indicates that the Capabilities Pointer (at dword 13) is valid, and points to the first capability register set.



    11



    Signalled Target Abort.
    This status bit indicates that a HyperTransport target has aborted and has signalled a non-NXA error response to the requestor. Cold Reset = 0.



    12



    Received Target Abort.
    This status bit indicates that a HyperTransport requestor has received a non-NXA error response to a request it issued. Cold Reset = 0.



    13



    Received Master Abort.
    This status bit indicates that a HyperTransport requestor has received an NXA (non-existent address) error to a request it has issued. The NXA error response is returned by the end-of-chain device acting on behalf of the intended target. This is equivalent to the Master abort event on PCI. Cold Reset = 0.



    14



    Signalled System Error.
    This status bit indicates that a HyperTransport device has flooded the link with Sync packets (indicating a serious error). A device merely forwarding Sync packets from another device should not set this bit; this allows identification of the offending device(s). A link reset is required before accessing the device. Cold Reset = 0.



    Other Bits



    All other header Status Register bits are unused in HyperTransport, and should be tied to a low level.





    Other Fields In The Header


    The use of other fields in the type 0 header region of a HyperTransport device include:


    Cache Line Size Register. (Offset 0Ch)

    This read-only register is not implemented by HyperTransport devices. Should return 0's if read by software.



    Latency Timer Register. (Offset 0Dh)

    This register is not implemented by HyperTransport devices. Should return 0's if read by software.



    Base Address Registers. (Offset 10h-24h)

    The six Base Address Registers (BARs) are used in much the same way as for PCI devices, with the following limits:


    I/O BAR

    For an I/O request, a single BAR is implemented. Only the lower 25 bits of the value programmed into the BAR is used for address comparison by the target, and the upper bits of the BAR should be written to zeros by system software. Any I/O request packet sent out on a link should have the start address bits 39-25 programmed for the I/O range in the HyperTransport memory map.



    Memory BAR

    A request for memory using 32-bit addressing can be accomplished using a single BAR, just as in PCI. This would limit the assigned target start address for the device to the lower 4GB of the 1 TB (40 bit) HyperTransport address map.


    Optionally, a HyperTransport device may support 64 bit address decoding, and use a pair of BARs to support it. If this is done, only the lower 40 bits of the 64 bit BAR memory address will be valid, and the upper bits are assumed to be zeros.


    Memory windows for HyperTransport devices are always assigned in BARs on 64-byte boundaries; this assures that even the largest transfer (16 dwords/64 bytes) will never cross a device address boundary. This is important because HyperTransport does not support a disconnect mechanism (such as PCI uses) to force early transaction termination.




    CardBus CIS Pointer. (Offset 28h)

    This register is not implemented by HyperTransport devices. Should return 0's if read by software.



    Capabilities Pointer. (Offset 34h)

    This field contains a pointer to the first advanced capability block. Because all HyperTransport devices have at least one advanced capability, this register is always implemented. The pointer is an absolute byte offset from the beginning of configuration space to the first byte of the first advanced capability register block.



    Interrupt Line Register. (Offset 3Ch)

    The HyperTransport Specification indicates that this register should be read-writable and may be used as a software scratch pad. The information routing information programmed into this register in PCI devices isn't required in HyperTransport because interrupt messages are sent over the links and sideband interrupts are not defined.



    Interrupt Pin Register. (Offset 3Dh)

    This register is reserved in the HyperTransport Specification. It may optionally be implemented for compatibility with software which may expect to gather interrupt pin information from all PCI-compatible devices.



    Min_Gnt and Max_Latency Registers. (Offsets 3Eh and 3Fh)

    These register fields are associated with PCI shared-bus arbitration, and are not implemented by HyperTransport devices. Should return 0's if read by software.




    HyperTransport Uses Advanced Capability Blocks


    The generic fields in the configuration space header region of a HyperTransport device are augmented by at least one HyperTransport-specific advanced capability register block. Software discovery of capability blocks was described in an earlier section. Figure 13-11 on page 331 illustrates the format of the advanced capability block register.


    Figure 13-11. HyperTransport Advanced Capability Block Types



    HyperTransport Block Types Currently Defined

    HyperTransport is allocated a number of advanced capability blocks for various purposes. All have the same Capability ID code (08 for HyperTransport) in the first byte of the block, but carry unique Type field codes. Table 13-3 on page 332 summarizes the HyperTransPort advanced capabilities and their type codes.



























































    Table 13-3. HyperTransport Advanced Capability Codes

    Code



    Capability Type



    000xx



    Slave/Primary Interface



    001xx



    Host/Secondary Interface



    01000



    Reserved (Switch)



    01001-01111



    Reserved



    10000



    Interrupt Discovery and Configuration



    10001



    Revision ID



    10010



    Reserved (UnitID Clumping)



    10011



    Reserved (Extended Configuration Space Access)



    10100



    Address Remapping



    10101-10111



    Reserved



    11000



    Reserved (Retry Mode)



    11001-11111



    Reserved




    Block Formats Vary With Capability And Device Type

    Each of the HyperTransport capability blocks has its own format. The Type field in the first dword of each capability block defines the format of the entire block. In addition, one of the principal capability block types (Slave/Primary Interface) also varies with the device which implements it because tunnel devices interface to two links and end (cave) devices interface to only one.




    The Slave/Primary Interface Block


    HyperTransport defines two principal advanced capability register block formats, Slave/Primary and Host/Secondary, which reflect the two possible roles a device interface can perform on a link. The Slave/Primary format is used by all tunnels and single-link peripheral (cave) devices. These devices never act as a host for a bus (they are slaves). In addition, because they are not bridges, they have a single primary interface to the bus and no secondary interfaces.


    One complicating factor is the fact that while an end (cave) device interfaces to only one link, a tunnel must interface to two links (still only one bus, though). To accommodate this difference, each Slave/Primary interface has two sets of link management registers, one for each link. A tunnel device implements one Slave/Primary interface and both sets of link management registers; an end (cave) device also implements one Slave/Primary interface but only one set of link management registers. Figure 13-12 illustrates these interfaces.


    Figure 13-12. Slave/Primary Interface For Tunnel And Cave Devices




    Description Of Slave/Primary Interface Fields


    The following section describes the use of each field in the Slave/Primary advanced capability interface block See Figure 13-13 on page 334. Most fields are the same as those in the Host/Secondary interface block. Note that the upper part of the first dword in any HyperTransport capability register contains the Type field. In this block type (and the Host/Secondary block that follows), only the upper three bits are used; the code "000" in these three bits indicate this is a Slave/Primary interface block. Unimplemented bits in this register block must be tied low.


    Figure 13-13. Slave/Primary Interface Block Format



    Capability ID Register. (Offset 00h)

    This read-only register is hard-wired to 08h for all HyperTransport advanced capability register blocks. This value is assigned by the PCISIG, and distinguishes HyperTransport advanced capability blocks from other types.



    Capabilities Pointer Register. (Offset 01h)

    This read-only register provides a byte offset (from the beginning of configuration space) to the next advanced capability block. If read as zero, there are no more advanced capability blocks to process.



    Slave Command Register. (Offset 02h-03h)

    This mixed read-only and read-write register contains fields used to set up the interface. The register is organized as shown in Figure 13-14 on page 335. Definition of the fields can be found in Table 13-4.


    Figure 13-14. HyperTransport Slave Command CSR




































    Table 13-4. Slave Interface Block Command Register Bit Assignment

    Bit



    Function



    4:0



    Base UnitID.
    Read-Write field programmed with the lowest numbered UnitID belonging to this device. Range: 0-1Fh. If multiple UnitIDs are requested (see next field), this value is the lowest numbered (base) UnitID. Warm Reset = 0.



    9:5



    Unit Count.
    Read only field indicating the number of UnitIDs this device requires assigned to it. Range 0-1Fh; total UnitID count per bus = 32.



    10



    Master Host.
    This read-write bit is set by hardware automatically to indicate which link is attached to the host. Any write to the Command register will cause this bit to be set to indicate which link the write arrived on. Warm Reset = 0.



    11



    Default Direction.
    This read-write bit determines the default direction requests should be sent when originating with this device. A "0" in this register indicates requests should be sent in the direction of the master host (see previous bit). A "1" indicates requests should be sent in the other direction. Bit has no meaning for a single-link device. Warm Reset = 0.



    12



    Drop On Un-init.
    This read-write bit sets the policy an uninitialized device should use for packets it would normally issue or forward if interface initialization were complete, but can't because it doesn't know if the interface is at the end of chain.


    If the uninitialized device has this bit cleared, it will stall until either its end-of-chain bit becomes set or initialization completes.


    If the uninitialized device has this bit set, it will behave as though its end-of-chain bit is set and reject packets instead of stalling.


    Cold Reset = 0.



    15:13



    Capability Type.
    Read only field indicating the type of information in this HyperTransport advanced capability block. Codes currently supported include:


    000 = Slave/Primary Interface Block


    001 = Host/Secondary Interface Block


    100 = Interrupt Discovery And Configuration


    101= Address Mapping


    Others = Reserved




    Link Control Registers. (Offset 04h and 08h)

    Slave/Primary interfaces implement two copies of this register, one for each link. For single link devices, only one Link Control Register would be active (0); for tunnels, both Link Control Registers would be active. The Slave Interface Link Control Registers are illustrated in Figure 13-15 on page 337, and the fields are described in Table 13-5 on page 337.


    Figure 13-15. Slave Interface Block Link Control Registers 0,1
























































    Table 13-5. Slave Interface Block Link Control Register 0,1 Bit Assignment

    Bit



    Function



    1



    CFIE (CRC Flood Enable).
    When this read-write bit is set = 1, sync flood will be initiated and the link fail bit (bit 4) will be set by this device whenever any CRC error bits for this link are asserted. Note that this bit has no effect on CRC error checking logic, which always is active for the entire bus width set up in the LinkWidthIn field of the corresponding Link Configuration Register. Warm Reset = 0.



    2



    CST (CRC Start Test).
    When this optional read-write bit is set = 1, device hardware initiates the CRC test sequence across the link. When the test is complete, hardware will clear this bit (which software can poll for completion). This feature should not be used unless the CRC Test Mode Capability bit has been checked for the device on the other end of the link.



    3



    CFE (CRC Force Error)
    This read-write bit is set by hardware to force bad CRC values on all data lanes enabled in the LinkWidthOut field of the corresponding Link Configuration Register. Data is not affected. Warm Reset = 0.



    4



    LkFail (Link Failure).
    This read only bit is set by hardware if a sync flood resulting from bad CRC, protocol violation, or flow control buffer overflow has been generated. It is only set by device which detected the error, not those that forward resulting sync packets. Cold Reset = 0.



    5



    Init (Initialization Complete).
    This read only bit is cleared by reset and set by hardware when the low-level link initialization sequence for both the transmit and receive interfaces on a link have completed successfully. If the interface is at the end of chain, the bit will not be set. Warm Reset = 0.



    6



    EOC (End Of Chain).
    This bit is set to indicate that the link is not part of a chain; packets moving toward this link are either dropped or rejected with an NXA error. CRC on the link is not checked and sync flood coming from this link is ignored. This bit may be set by hardware (detecting all inputs low at reset) or by software seeking to partition a double-hosted chain. Bit can only be cleared by reset. Single-link slave devices hard-wire this bit =1 on the unused link. Warm reset = 0.



    7



    TXO (Transmitter Off).
    This Read/Set bit is used to disable the transmitter drivers on a link for power savings or EMI reduction. When set = 1, device outputs are steady-state, and the corresponding receiver at the other end of the link may also have to be disabled. Reset clears this bit; once set by software, it can only be cleared by a subsequent reset. Warm reset = 0.



    11:8



    CRC Error.
    These four bits are used to log CRC errors on a per-byte basis. bit 8 logs errors for CAD bits 0-7; bit 9 for CAD bits 8-15; bit 10 for CAD bits 16-23; bit 10 for CAD bits 24-31. Bits for unimplemented byte lanes or lanes disabled in Max Link Width In field of Link Configuration Register should return 0's when read. Cold Reset = 0.



    12



    IsoEn (Isochronous Enable).
    When this optional read-write bit is set = 1, isochronous mode flow control is enabled. This traffic is generally given the highest possible priority with respect to other virtual channel traffic in HyperTransport. Isochronous support is optional, and this bit should not be set unless the device on the other end of the link has been checked for isochronous support as well. Any device that detects isochronous packets but doesn't support them, simply handles them in the standard posted, non-posted, and response virtual channels. Cold reset = 0.



    13



    LSEn (LDTSTOP# Tristate Enable).
    When this read-write bit is set = 1, the link transmitter tristates the link (CAD, CTL, CLK) during the disconnected state of an LDTSTOP# sequence. If the bit is clear, the transmitter continues driving its outputs during these events. Cold reset = 0.



    14



    ExtCTL (Extended CTL Assertion Time).
    When this read-write bit is set = 1, during a link initialization sequence, CTL will be asserted for 50uS after both are true: the transmitter has asserted its CTL and it also has sampled the CTL from the other side of the link as well. If the bit is clear, both CTL assertions only have to be true for 16 bit times for 8-32 bit links, 32 bit times for 4 bit links, or 64 bit times for two bit links. The extended time is for the benefit of receivers using DLL's, and requiring additional time to lock to the input clock after a LDTSTOP# sequence. Cold reset = 0.






    Link Configuration Registers. (Offset 06h and 0Ah)

    Slave/Primary interfaces also implement two copies of this register, one for each link. For single link devices only one Link Configuration Register would be active; for tunnels, both Link Configuration Registers would be active. The Slave Interface Link Configuration Register is illustrated in Figure 13-16 on page 340. The field definitions can be found in Table 13-6 on page 340.


    Figure 13-16. Slave Interface Link Configuration Registers 0,1












































    Table 13-6. Slave Interface Block Link Configuration Register 0,1 Bit Assignment

    Bit



    Function



    2:0



    Max Link Width In.
    This read only register is hard coded to indicate the maximum width of the receive side of this link. HyperTransportv supports CAD bus widths of 2-32 bits in each direction. The 3 bits in this field are coded as follows: (all other codes are reserved)


    000 = 8 bits wide


    001 = 16 bits wide


    011 = 32 bits wide


    100 = 2 bits wide


    101 = 4 bits wide


    111 = Link Not Connected



    3



    DW FC In (Doubleword Flow Control In Capability).
    If this read-only bit is set = 1, the receiver is capable of double-word based flow control.



    6:4



    Max Link Width Out.
    This read only register is hard coded to indicate the maximum width of the transmit side of this link. HyperTransportv supports CAD bus widths of 2-32 bits in each direction. The 3 bits in this field are coded in the same way as the receive side: (all other codes are reserved)


    000 = 8 bits wide


    001 = 16 bits wide


    011 = 32 bits wide


    100 = 2 bits wide


    101 = 4 bits wide


    111 = Link Not Connected



    7



    Dw Fc Out (Doubleword Flow Control Out Enable).
    If this read-only bit is set = 1, the transmitter is capable of double-word based flow control.



    10:8



    Link Width In.
    This read-write field is written by software to establish the actual width to be utilized for the receive side of this link. After a cold reset, low-level device negotiation establishes the starting input width (maximum 8 bits) and presets the code in this register to reflect it. After software checks the link width capabilities of both devices, it may rewrite the value in this register to use a different width. The 3 bits in this field are coded as follows: (all other codes are reserved)


    000 = 8 bits wide


    001 = 16 bits wide


    011 = 32 bits wide


    100 = 2 bits wide


    101 = 4 bits wide


    111 = Link Not Connected


    Cold reset = 0.



    11



    DW FC In EN (Doubleword Flow Control In Enable).
    This read-write bit may be written = 1 to program the receiver to use double-word based flow control. Software should not program this capability before checking that devices on both sides of the link are capable of using this optional mode (see bit 3 and bit 7). Cold reset = 0.



    14:12



    Link Width Out.
    This read-write field is written by software to establish the actual width to be utilized for the transmit side of this link. After a cold reset, low-level device negotiation establishes the starting transmit width (maximum 8 bits) and presets the code in this register to reflect it. After software checks the link width capabilities of both devices, it may rewrite the value in this register to use a different transmit width. The 3 bits in this field are coded as follows: (all other codes are reserved)


    000 = 8 bits wide


    001 = 16 bits wide


    011 = 32 bits wide


    100 = 2 bits wide


    101 = 4 bits wide


    111 = Link Not Connected


    Cold reset = 0.


    Note:
    CAD bit width downsized through programming of Link Width Out field will result in unused drivers being shut down.



    15



    DW FC Out EN (Doubleword Flow Control Out Enable).
    This read-write bit may be written = 1 to program the transmitter to use double-word based flow control. Software should not program this capability before checking that devices on both sides of the link are capable of using this optional mode (see bit 3 and bit 7). Cold reset = 0.




    Revision ID Register. (Offset 0Ch)

    This 8 bit field indicates the Major and Minor revision of the HyperTransport I/O Link Protocol Specification to which this interface complies (See Figure 13-17). For example, if the interface was compliant with Link Protocol Specification 1.03, then:


    Major Rev: 01


    Minor Rev: 03


    Figure 13-17. Slave Interface Revision ID Register




    Link Frequency Registers. (Offset 0Dh and 11h)

    Slave/Primary interfaces implement two copies of this register, one for each link. Figure 13-18 illustrates the slave interface Link Frequency Register, along with the possible values. For single link devices, only one Link Frequency Register would be active (0); for tunnels, both Link Frequency Registers would be active. The value in this field determines the actual clock frequency to be used on the link. After reset, the default rate of 200MHz is used and the code 000 is in this register. Software may later write a non-zero value to the register after devices on both ends of the link have been checked for clock speed capability (see Link Freq Cap Register). A warm reset or LDTSTOP# sequence is required for frequency change to take effect. Devices must support the 200MHz rate; all others are optional.


    Figure 13-18. Slave Interface Link Frequency Registers 0,1




    Link Error Registers. (Offset 0Dh and 11h)

    Slave/Primary interfaces implement two copies of this register, one for each link. Figure 13-19 illustrates the slave interface Link Error Register, and Table 13-7 defines the fields. For single link devices, only one Link Error Register would be active; for tunnels, both Link Error Registers would be active.


    Figure 13-19. Slave Interface Link Error Registers 0,1




























    Table 13-7. Slave Interface Link Error Registers 0,1

    Bit



    Function



    4



    Protocol Err.
    This bit is set by hardware if a protocol error is detected on this link. Cold reset = 0.



    5



    Overflow Err.
    This bit is set by hardware if an overflow error is detected on this link. Cold reset = 0.



    6



    EOC Err.
    This bit is set by hardware if a protocol error is detected on this link. Cold reset = 0.



    7



    CTL Time out.
    This bit is hard coded to indicate the time CTL may be detected low before a protocol error is reported. If bit 7 = 1, maximum low time is 1 second; if bit 7 = 0, maximum low time is 1 millisecond




    Link Frequency Capability Registers. (Offset 0Eh and 12h)

    Slave/Primary interfaces implement two copies of this register, one for each link. Figure 13-20 illustrates the slave interface Link Frequency Capability Register, and Table 13-8 on page 347 defines the fields. For single link devices, only one Link Frequency Capability Register would be active (0); for tunnels, both Link Frequency Capability Registers would be active. Value hard coded is a mask of all speed capabilities.


    Figure 13-20. Slave Interface Link Frequency Capability Registers 0,1
















































    Table 13-8. Slave Interface Link Frequency Capability Registers 0,1

    Bit



    Function



    0



    200 MHz Supported.
    This read only bit (if set = 1) indicates device supports 200MHz clock speed for this link. This is the default clock speed and all devices should have this bit set for each active link.



    1



    300 MHz Supported.
    This read only bit (if set = 1) indicates device supports 300MHz clock speed for this link. Support is optional.



    2



    400 MHz Supported.
    This read only bit (if set = 1) indicates device supports 400MHz clock speed for this link. Support is optional.



    3



    500 MHz Supported.
    This read only bit (if set = 1) indicates device supports 500MHz clock speed for this link. Support is optional.



    4



    600 MHz Supported.
    This read only bit (if set = 1) indicates device supports 600MHz clock speed for this link. Support is optional.



    5



    800 MHz Supported.
    This read only bit (if set = 1) indicates device supports 800MHz clock speed for this link. Support is optional.



    6



    1GHz Supported.
    This read only bit (if set = 1) indicates device supports 1GHz clock speed for this link. Support is optional.



    14:7



    Reserved.
    These bits are currently reserved and unused. Devices should tie them low.



    15



    Vendor Specific Speed Support.
    If this bit is set, device supports vendor-specific clock frequencies. Usage is beyond scope of HyperTransport Specification.




    Feature Capability Register. (Offset 10h)

    This register is used to indicate to software which optional features are supported by this device. See Figure 13-21 on page 348. Table 13-9 on page 348 defines each bit field. All unspecified bits are reserved, and should read back as zero.


    Figure 13-21. Slave Interface Feature Capability Register




























    Table 13-9. Slave Interface Feature Capability Register

    Bit



    Function



    0



    Isochronous Mode.
    This read only bit (if set = 1) indicates device supports the optional Isochronous flow control mechanism. If this bit is clear, the device will handle packets with Isoc bit set as standard virtual channel traffic. Software should check this bit for both devices on a link before enabling isochronous traffic (see bit 12 of Link Control Register).



    1



    LDTSTOP#.
    This read only bit (if set = 1) indicates device supports the optional LDTSTOP# protocol.



    2



    CRC Test.
    This read only bit is set = 1 if device supports optional CRC test mode



    3



    Extended CTL Time Required.
    This read only bit indicates whether device requires CTL signal to be asserted for the extended 50uS time following LDTSTOP# disconnect in order to allow time to reacquire lock to input clock. Bit is set = 1 if the extended time is needed; cleared otherwise.




    Enumeration Scratch Pad Register. (Offset 14h)

    As illustrated in Figure 13-22, this 16 bit register provides a read-writable register for software to use during the enumeration process. Cold reset = 0.


    Figure 13-22. Slave Interface Enumeration Scratch Pad Register




    Error Handling Register. (Offset 16h)

    This register contains bits that enable the error routing strategy for the device as well as status bits used to log chain fail and response error events. See Figure 13-23. Table 13-10 defines each bit field. Devices that don't support a particular error condition should hard wire the logging and enable bits for that event to zero.


    Figure 13-23. Slave Interface Error Handling Register












































































    Table 13-10. Slave Interface Error Handling Register

    Bit



    Function



    0



    Protocol Error Flood Enable.
    This read-write bit, when set = 1, indicates the device should flood the link with Sync packets anytime a protocol error bit is set in one or more of its Link Error registers. Warm reset = 0.



    1



    Overflow Error Flood Enable.
    This read-write bit, when set = 1, indicates the device should flood the link with Sync packets anytime an overflow error bit is set in one or more of its Link Error registers. Warm reset = 0.



    2



    Protocol Error Fatal Enable.
    This read-write bit, when set = 1, indicates the device should issue a fatal error interrupt in the event a protocol error bit is set in one or more of its Link Error registers. If fatal interrupt not implemented, hard wire this bit = 0. Warm reset = 0.



    3



    Overflow Error Fatal Enable.
    This read-write bit, when set = 1, indicates the device should issue a fatal error interrupt in the event an overflow error bit is set in one or more of its Link Error registers. If fatal interrupt not implemented, hard wire this bit = 0. Warm reset = 0.



    4



    End Of Chain Error Fatal Enable.
    This read-write bit, when set = 1, indicates the device should issue a fatal error interrupt if the EOC error bit is set in one of its Link Error Registers. Warm reset = 0.



    5



    Response Error Fatal Enable.
    This read-write bit, when set = 1, indicates the device should issue a fatal error interrupt if the Response Error bit is asserted (see bit 9 in this register). Warm reset = 0.



    6



    CRC Error Fatal Enable.
    This read-write bit, when set = 1, indicates the device should issue a fatal error interrupt whenever any of the CRC Error bits are asserted in any of its Link Control Registers. Warm reset = 0.



    7



    System Error Fatal Enable.
    This bit is hardcoded = 0 for slave interfaces.



    8



    Chain Fail.
    This bit is used to indicate that the chain to which this device is attached has gone down. It is set by hardware whenever the device either detects a sync flood or an error which will cause it to generate a sync flood. Warm reset = 0.



    9



    Response Error.
    This status bit is set by the device to indicate that it has received a response error. Cold reset = 0.



    10



    Protocol Error Nonfatal Enable.
    This read-write bit, when set = 1, indicates the device should issue a nonfatal error interrupt in the event a protocol error bit is set in one or more of its Link Error registers. If nonfatal error interrupts are not supported, hard wire this bit = 0. Warm reset = 0.



    11



    Overflow Error Nonfatal Enable.
    This read-write bit, when set = 1, indicates the device should issue a nonfatal error interrupt in the event an overflow error bit is set in one or more of its Link Error registers. If nonfatal error interrupts are not supported, hard wire this bit = 0. Warm reset = 0.



    12



    End Of Chain Error Nonfatal Enable.
    This read-write bit, when set = 1, indicates the device should issue a nonfatal error interrupt if the EOC error bit is set in one of its Link Error Registers. If nonfatal error interrupts are not supported, hard wire this bit = 0. Warm reset = 0.



    13



    Response Error Nonfatal Enable.
    This read-write bit, when set = 1, indicates the device should issue a nonfatal error interrupt if the Response Error bit is asserted (see bit 9 in this register). If nonfatal error interrupts are not supported, hard wire this bit = 0. Warm reset = 0.



    14



    CRC Error Nonfatal Enable.
    This read-write bit, when set = 1, indicates the device should issue a nonfatal error interrupt whenever any of the CRC Error bits are asserted in any of its Link Control Registers. If nonfatal error interrupts are not supported, hard wire this bit = 0. Warm reset = 0.



    15



    System Error Nonfatal Enable.
    This bit is hardcoded = 0 for slave interfaces.




    Memory Base Upper Register. (Offset 18h)

    This 8 bit register is used only by bridges. Concatenating this 8 bits with the 32 bits programmed in to the bridges 32 bit Memory Base Register (in the bridge header region) allows extending the start (base) address for non-prefetchable addresses behind the bridge to the full 40 bits required by HyperTransport. Warm reset = 0.



    Memory Limit Upper Register. (Offset 19h)

    This 8 bit register is also used only by bridges. See Figure 13-24 on page 353. Concatenating this 8 bits with the 32 bits programmed in to the bridges 32 bit Memory Limit Register (in the bridge header region) allows extending the maximum address for non-prefetchable addresses behind the bridge to the full 40 bits required by HyperTransport. Warm reset = 0.


    Figure 13-24. Slave Interface Memory Base/Limit Upper Registers



    Note:
    The Memory Base and Memory Upper extension registers are needed because PCI compatible bridges typically don't allow accesses to addresses above 4GB (32 bits) for non-prefetchable memory, and only provide a 32 bit base-limit register pair to manage this space. Prefetchable memory is allowed above 4GB, and the bridges already have extension registers to manage this space.




    TheHost/Secondary Interface Block


    The following section describes the Host/Secondary advanced capability interface block. Most fields are the same as those in the Slave/Primary interface block. This interface is implemented by devices which are required to act as a the host bridge for a HyperTransport chain. Such devices would include:



    • Host Bridges connecting a CPU bus (or other protocol) to HyperTransport. Host bridges implement a single Host/Secondary interface with one set of link management registers.


    • HyperTransport-HyperTransport bridges between chains. The bridge implements a Slave/Primary interface for its upstream connection, and one Host/Secondary interface block for each secondary bus it supports. If the bridge also implements a tunnel function, it will manage two sets of link management registers with its Slave/Primary interface.



    Figure 13-25 on page 354 depicts the host bridge and HyperTransport-HyperTransport bridge (with tunnel) cases.


    Figure 13-25. Host/Secondary Interface For Bridge Devices




    Description Of Host/Secondary Interface Fields


    The following section describes the use of each field in the Host/Secondary advanced capability interface block. Most fields are the same as those in the Slave/Primary interface block. As in the case of the Slave/Primary block, the upper three bits in the Command register encodes the interface block format, as depicted in Figure 13-26. Code 001 indicates the Host/Secondary block format.


    Figure 13-26. Host/Secondary Command Register Format.



    Capability ID Register. (Offset 00h)

    This read-only register is hard-wired to 08h for all HyperTransport advanced capability register blocks. This value is assigned by the PCISIG, and distinguishes HyperTransport advanced capability blocks from other types.



    Capabilities Pointer Register. (Offset 01h)

    This read-only register provides a byte offset (from the beginning of configuration space) to the next advanced capability block. If read as zero, there are no more blocks to process.



    Host Command Register. (Offset 02h-03h)

    This mixed read-only and read-write register contains fields used to set up the host/secondary interface. The register is organized as shown in Figure 13-27 on page 356, and each bit field is defined in Table 13-11.


    Figure 13-27. HyperTransport Host Command CSR




















































    Table 13-11. Host Interface Block Command Register Bit Assignment

    Bit



    Function



    0



    Warm Reset.
    If this read-write bit is set = 1, the a secondary bus reset caused by asserting the Secondary Bus Reset bit in the Bridge Control Register will be a warm reset (reset with PWROK asserted). If this bit is clear, then the secondary bus reset will be a cold reset (PWROK also driven low). If not implemented, hard wire this bit = 0. If implemented, default = 1.



    1



    Double Ended.
    If this read-write bit is set = 1, there is another bridge at the other end of the chain (double-hosted chain). This bit does not affect hardware and can be used by software during initialization. If not implemented, hard wire this bit = 0. Cold reset = 0.



    6:2



    Device Number.
    This optional field is used to program a device number that the interface can respond to during configuration cycles initiated from the chain side. Device number is typically zero, but could be a different value for compatibility or ordering reasons.


    The value programmed in this register is used as the UnitID of hosts with the Act As Slave bit set (see bit 10). If the Act As Slave bit is implemented, this bit must also be implemented. If not implemented, hard wire this bit = 0. Cold reset = 0.



    7



    Chain Side.
    This bit is set to indicate which side of the host bridge is being accessed. A 0 in this bit indicates the read is coming from within; a 1 indicates the read is coming from the chain attached to the host interface. If double-hosted chains are not supported, this bit is 0.



    8



    Host Hide.
    This read-write bit is used to hide a bridges configuration space from accesses coming from the chain side. If the bit is set = 1, the host will behave as an end-of-chain device; if it is clear, configuration accesses from the chain are allowed by the device. Warm reset = 0. If the device does not support double-hosted chains, this bit is always = 1.



    9



    Reserved.



    10



    Act As Slave.
    This bit, when set, causes host to act as a slave, using the device number programmed in bits 6:2 as the base UnitID for requests and responses sources. In this mode, the host also won't set the Bridge bit in its responses. If this bit is clear, interface behaves as a host � using UnitID 0, setting the Bridge bit on responses it sends, etc. If host doesn't support double-hosted chains, this bit may be hard wired = 0.



    11



    Inbound EOC Err.
    This bit is set by hardware to indicate a mis-directed packet was received from a far host (in a double-hosted chain) and has handled it as an end-of-chain error (much as any other device handles end-of-chain errors). If the host doesn't check fro such errors, it hard wires this bit = 0. Cold reset = 0.



    12



    Drop On Un-init.
    This read-write bit sets the policy an uninitialized device should use for packets it would normally issue or forward if interface initialization were complete, but can't because it doesn't know if the interface is at the end of chain.


    If the uninitialized device has this bit cleared, it will stall until either its end-of-chain bit becomes set or initialization completes.


    If the uninitialized device has this bit set, it will behave as though its end-of-chain bit is set and reject packets instead of stalling.


    Cold Reset = 0.



    15:13



    Capability Type.
    Read only field indicating the type of information in this HyperTransport advanced capability block. Codes currently supported include:


    000xxb = Slave/Primary Interface Block


    001xxb = Host/Secondary Interface Block


    01000b = Reserved (Switch)


    10000b = Interrupt Discovery And Configuration


    10001 = Revision ID


    10100b= Address Mapping


    11000b = Reserved (Retry Mode)


    Others = Reserved






    Link Control Register. (Offset 04h)

    Host/Secondary interfaces connect to a single link, and implement only one copy of this register to support it. The format for this register is the same as for the Slave/Primary block already described.



    Link Configuration Register. (Offset 06h)

    Host/Secondary interfaces connect to a single link, and implement only one copy of this register to support it. The format for this register is the same as for the Slave/Primary block already described.



    Revision ID. (Offset 08h)

    This 8 bit field indicates the Major and Minor revision of the HyperTransport I/O Link Protocol Specification to which this interface complies. The format for this register is the same as for the Slave/Primary block already described.



    Link Frequency AndLink Error Registers. (Offset 09h)

    The format for these registers is the same as for the Slave/Primary block already described.



    Link Frequency Capability. (Offset 0Ah)

    The format for this register is the same as for the Slave/Primary block already described.



    Feature Capability Register. (Offset 0Ch)

    The Feature register in the Host/Secondary interface is slightly different than the one used for Slave/Primary interfaces. It is a 16 bit register (instead of 8), and adds one more bit field. (See Figure 13-28.) The bits are described in Table 13-12.


    Figure 13-28. Host Interface Feature Capability Register




































    Table 13-12. Host Interface Feature Capability Register

    Bit



    Function



    0



    Isochronous Mode.
    This read only bit (if set = 1) indicates device supports the optional Isochronous flow control mechanism. If this bit is clear, the device will handle packets with Isoc bit set as standard virtual channel traffic. Software should check this bit for both devices on a link before enabling isochronous traffic (see bit 12 of Link Control Register).



    1



    LDTSTOP#.
    This read only bit (if set = 1) indicates device supports the optional LDTSTOP# protocol.



    2



    CRC Test.
    This read only bit is set = 1 if device supports optional CRC test mode.



    3



    Extended CTL Time Required.
    This read only bit indicates whether device requires CTL signal to be asserted for the extended 50uS time following LDTSTOP# disconnect in order to allow time to reacquire lock to input clock. Bit is set = 1 if the extended time is needed; cleared otherwise.



    8



    Extended Register Set.
    This read only bit indicates whether the following optional registers are implemented: Error Handling, and Memory Base/Limit Upper Registers. If this bit is clear, no attempt should be made to access any of these registers.


    Note:
    Implementing the extended register set is strongly recommended for host/secondary interfaces but required for slave/Primary Interface blocks. This is the reason this bit is not present in the host/secondary interface block.



    Other Bits



    Reserved.
    Should read back as zero.




    Enumeration Scratchpad Register. (Offset 10h)

    If support is indicated in bit 8, the format of this register is the same as for the Slave/Primary block already described.



    Error Handling Register. (Offset 12h)

    If support is indicated in bit 8, the format of this register is the same as for the Slave/Primary block already described.



    Memory Base/Limits Upper Registers. (Offset 14h, 15h)

    If support is indicated in bit 8, the format of these registers is the same as for the Slave/Primary block already described.




    Revision ID Capability Block


    Each HyperTransport function is required to report the revision of the HyperTransport specification to which it complies. This can be done in the Revision ID field of the Slave/Primary or Host/Secondary Interface block, or by implementing the Revision ID advanced capability block described here. Figure 13-29 on page 361 illustrates the format of the RevisionID capability block, and the fields are described in Table 13-13.


    Figure 13-29. Revision ID Capability Block




























    Table 13-13. Revision ID Capability Block Bit Assignment

    Bits



    Function



    31:24



    Capability Type.
    For the Revision ID Capability Block, the upper five bits are used and code is 10001b



    23:16



    Revision ID code.
    Bits 23:20 = Major Rev; Bits 19:16 = Minor Rev. For example, if the HyperTransport function complies with the 1.03 revision of the specification, this field would be hardcoded to 0103h.



    15:8



    Capability Pointer.
    This is the offset (in bytes) to the next advanced capability register block. Value programmed here is the offset from the beginning of configuration space. A value of zero hardcoded here indicates that this is the last advanced capability block.



    7:0



    Capability ID.
    This identifies the protocol being supported by this block. 08h is hardcoded here for all HyperTransport capability blocks.









      [ Team LiB ]