dptarget.c

VXWORKS源代码

/*
**  File:   dptarget.c
**  Description:
**    This file contains routines which are meant to be used by target
**    systems when communicating with the NetROM emulator through Pod 0's
**    dualport ram.
**
**      Copyright (c) 1996 Applied Microsystems Corporation
**                          All Rights Reserved
**
** Redistribution and use in source and binary forms are permitted 
** provided that the above copyright notice and this paragraph are 
** duplicated in all such forms and that any documentation,
** advertising materials, and other materials related to such
** distribution and use acknowledge that the software was developed 
** by Applied Microsystems Corp. (the Company).  The name of the 
** Company may not be used to endorse or promote products derived
** from this software without specific prior written permission. 
** THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR 
** IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
** WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. 
**
**  Modification History:
   2/18/94 fdv add two out of band characters to readaddr protocol:
                RA_RESET and RA_RESYNC.
                RA_RESET lets the target trigger a tgtreset.
                RA_RESYNC lets the target trigger the netrom initialize
                    the dualport.

   4/7/94 fdv 1. fixed ra_reset and ra_resync. 2. modified read addr reads
              to "read away" cause of problem seen with ev960ca demo board.
 
   5/4/94 fdv added MISC out of band character to readaddr:
		subfunction is receive interrupt ack.
   5/27/94 fdv added MISC out of band character to readaddr:
		subfunction is turn off emulate before ra_setmem.
   6/16/94 fdv fix to emoffonwrite, it was being called on every set_mem
   2/23/95 sch Add virtual ethernet, both ReadAddr and ReadWrite
   8/21/95 sch Add read after write check to dp_readint().  This
               fixes a data corruption problem when sending large
               amounts of data to the host with little traffic from
               the host.
	   sch Cleanup: Change xchannels back to channels, delete unused
               OVERFLOW_MSGS code.
	   sch Add protocol to end of ra_resync().  Wait for NetROM to
	       turn off RI and then turn it back on before exiting, so
	       the target will not try to send or receive until NetROM
	       is done with the resync.
	   sch More cleanup.  Fix declarations of several routines so 
	       they will agree with their usage.
	   sch In config_dpram, avoid divides when setting oobthresh
	       for readaddr.
	   sch In dp_bread and dp_bwrite, call READ_POD and WRITE_POD
	       if HASCHACHE is true.  These routines will deal with
	       turning off the cache.
    10/12/95 sch Clean up the ra_resync mod.  Take out delay at start.
           Only wait for RI to go on before returning (NetROM will turn
           it off before acking the last RE_RESYNC char).
*/

/**********************************************************************
    Porting notes:
                                OVERVIEW
        This file contains routines which are meant to be used by target
    systems when communicating with the NetROM emulator through Pod 0's
    dualport ram.  These routines are byte-oriented for both transmit and
    receive; however, multibytes messages are passed between target and
    NetROM whenever possible, to reduce handshaking overhead.  Data is
    collected at the target/NetROM interface a byte at a time and passed
    over in messages.
        Messages are fixed-size, fixed format data structures, whose format
    is as follows:
                -----------------------------------------
                | Flags | Size |         Data           |
                -----------------------------------------

                    ^      ^               ^
                    |      |               |
                  2 bytes  |               |
                        2 bytes            |
                                       60 bytes
    Flag values are:
        0x8000          Message ready bit
        0x0001          Start of message bit (for multiple structure messages)
        0x0002          End of message bit (for multiple structure messages)
        0x0004          Message structure Wrap bit
    The Start and End bits are both set in single structure messages.
    The Wrap bit is used to mark the end of an array of structures (for
    example, the transmit array).
    The size field of the structure indicates how many of the data bytes
    are valid.  The size does not include the Flags or the Size field.
    The message structure is described in more detail in the include file,
    dualport.h.
        The protocol between target and NetROM has two distinct flavors;
    one for targets which are capable of writing dualport ram and one for
    targets which can only read dualport ram.  In general, the target will
    poll dualport ram for messages; messages will be ready to process when the
    Ready bit is set.  The scenarios for transmitting data to NetROM are
    different for targets which have write capability and those which do
    not; they are described below.  A key feature of the transmit path
    from target to NetROM is the target's ability to cause an interrupt
    to the NetROM by *reading* special areas of dualport ram.  When NetROM
    receives the interrupt, it uses the target's read address to extract
    an eight-bit value.  The value is equal to the offset of the target's
    read address from the start of the interrupt-causing area of dualport
    ram.
        *** Note *** an important issue in communicating with the NetROM is
    avoiding collisions when accessing dualport ram.  In situations where
    the target and NetROM both access the same dualport address, the target
    will lose.  That is, it will read garbage, or its writes may fail.  This
    is an unavoidable issue, caused by the asynchronous nature of target
    accesses to emulation pod memory, including dualport ram.
        Avoiding access collisions when the target sends data to NetROM is
    accomplished by the NetROM not polling for messages written by the
    target.  Rather, when the target is done writing a message, it sends an
    interrupt to the NetROM by reading a special address in dualport ram.
    Only when the NetROM receives the interrupt will it check dualport ram for
    messages from the target.  If the target cannot write dualport ram,
    all data is passed by read-address interrupts, so access collisions are
    not a problem.
        Access collisions when the NetROM writes messages are unavoidable
    because the target must poll dualport ram for messages.  However, the
    NetROM will only write each byte of ram one time, so the target can
    verify the Ready bit being set in a message, simply by reading the flags
    field twice.  Since NetROM will only set the Ready bit after it has
    written the message data, the target only needs to perform a "verification"
    on the flags fields of message structures.

                            READ-WRITE TARGETS
        Targets which can write dualport ram will use a dualport memory layout
    consisting of an array of 64-byte structures.  There will be 15 receive
    structures and 16 transmit data structures.  Receive structures will
    contain messages written by NetROM and transmit structure will be
    used to send data to NetROM.  The configuration/status structure is
    used to indicate whether or not NetROM is ready to process messages,
    and reading parts of the configuration/status structure will send
    interrupts to NetROM.
                --------------------------------------------
                |       Configuration/Status Structure (*) |
                --------------------------------------------
                |       RX Message Structure 0             |
                --------------------------------------------
                |               ...                        |
                --------------------------------------------
                |       RX Message Structure 14            |
                --------------------------------------------
                |       TX Message Structure 0             |
                --------------------------------------------
                |               ...                        |
                --------------------------------------------
                |       TX Message Structure 15            |
                --------------------------------------------

        The configuration/status structure for targets with write
    capability is simple:
                --------------------------------------------
                | Interrupt Area | TX | RX |   Reserved    |
                --------------------------------------------
                        ^           ^    ^          ^
                        |           |    |          |
                     8 bytes        |    |          |
                                  1 byte |          |
                                       1 byte       |
                                                54 bytes
    The target may read from the interrupt area to generate an interrupt
    to the NetROM.  Upon receipt of this interrupt, the NetROM will check
    the dualport message area for messages from the target.  The TX and
    RX bytes are used to indicate when the NetROM is ready to process
    messages and interrupts.  *** The target should not cause interrupts
    unless these bytes are set, because NetROM will not detect a missed
    interrupt. ***

                            READ-ONLY TARGETS
	Targets which can read but not write dualport ram must use a
    different mechanism to send data to the NetROM.  NetROM
    contains a special area of memory in Pod 0 which, when read by the
    target, causes an interrupt to be generated to NetROM's processor.
    NetROM can determine which address within the 256-byte area was
    read, and uses this address to calculate an 8-bit number.  Using
    this mechanism, it is possible for the target to send 8-bit data to
    the NetROM.  Sending certain 8-bit values is done in two steps.
    This is because there are situations in which it is necessary to
    send out-of-band data to the NetROM; that is, data which is
    relevant to the protocol but not the the content of messages the
    target wants to send.  For example, when the target reads a message
    structure written by the NetROM, it cannot clear the Ready bit in
    the message's flags.  Thus, it uses a special value (that is,
    address) to acknowlege messages received from the NetROM.
    Distinguishing between ACKs (0xF8) and equivalent values in message
    data would require a character-stuffing protocol, which is not
    currently supported.  Thus data values greater than 0xF8 are sent
    in two or more pieces. The first, an "escape" character (0xF9),
    tells NetROM to add 0xF8 to the next character received. The second
    piece is the original value minus 0xF8.  This "character stuffing"
    only needs to be done for values greater than 0xF8.
	The SET character (0xF2) is used when the target system wishes to 
    request that NetROM modify the contents of emulation memory.  After
    receiving the SET character, NetROM will interpret the next four
    characters as an offset into emulation memory, received most-significant
    byte first.  Following the offset is an 8-bit value to be written.  Note
    that the target software should run from RAM from the time it transmits
    the value character to the time that NetROM acknowleges the value
    character.  This is to prevent memory contention problems.  The set
    function is implemented by ra_setmem() in this file.
	The START and END characters are used to delineate a complete message
    being sent via the read-address protocol.  They are analogous to the START
    and END bits in a dualport message structure.  These out-of-band
    characters are useful when using a UDP transport between NetROM and the
    host system, since each UDP datagram will contain a complete message.
    Sending messages is implmented in the ra_putmsg() routine in this file.
        There is an added subtlety in the read-address protocol, which is
    that NetROM is unable to detect missed interrupts.  As a result, prior
    to sending each character, the target must be sure that NetROM is
    listening for interrupts, and that the character that was sent was
    received.  There are two fields in the configuration/status structure
    which accomplish this; one which is set when the NetROM is listening
    for interrupts, and one which is incremented for each character
    (including control characters) that the target sends.  These are described
    below.  Note that the values of all escape characters are different for 
    target systems which perform burst reads from emulation pod 0.  Consult
    your netrom manual for information on these types of systems.
        The target receives messages from the NetROM using a similar
    protocol to that used by the read-write target.  However, it must
    acknowlege each message with a special character, since it cannot
    clear Ready bits itself.

    /--------  256-byte read-address area; target reads of this area
    |       generate interrupts to the NetROM.
    |
    |   /--     --------------------------------------------
    |   |       |                                          |
    |   |       --     248-byte ASCII Read-address Data   --
    --->|       |                                          |
        |       --------------------------------------------
        |       |    Control Read-address Data (8 bytes)  |
        \--     --------------------------------------------
                |       Configuration/Status Structure     |
                --------------------------------------------
                |       RX Message Structure 0             |
                --------------------------------------------
                |               ...                        |
                --------------------------------------------
                |       RX Message Structure 26            |
                --------------------------------------------

     The layout of the control read-address data area.
     --------------------------------------------------------------
     | PACK | ESC | SET | START | END | RESET | RESYNC | MISC |
     --------------------------------------------------------------
        ^      ^     ^      ^      ^      ^        ^       ^
        |      |     |      |      |      |        |       |
     1 byte    |     |      |      |      |        |       |
            1 byte   |      |      |      |        |       | 
	          1 byte    |      |      |        |       |
		         1 byte    |      |        |       |
			        1 byte    |        |       |
				       1 byte      |       |
						1 byte     |
                                                         1 byte

    The PACK byte is used to tell NetROM that a single message has been
    received from dualport RAM.  This byte should be read after *every*
    dualport message.  The ESC byte is used to tell NetROM that the data
    being transmitted is greater or equal in value than 248 (0xF8).  When
    NetROM receives an ESC character, it will add 0xF8 to the character
    which follows, and pass the result to higher level protocols as if it
    were received in a single transmission. RESET lets the target trigger 
    a tgtreset. RESYNC lets the target trigger the netrom initialize the 
    dualport. MISC allows more control by parsing the next char for a
    subfunction. The subfuntions are:
	0x1  Receive Interrupt Acknowledge.
	0x2  turn off emulate mode before performing ra_setmem.


        The layout of the configuration/status structures.
                --------------------------------------------
                | RI | ACK |           Reserved            |
                --------------------------------------------
                   ^    ^                  ^
                   |    |                  |
                1 byte  |                  |
                     1 byte                |
                                       62 bytes

    The RI bit indicates that NetROM is ready to handle interrupts.
    The ACK byte is an 8-bit counter, which is incremented for each character
    which the NetROM receives, including control characters such as
    acks.

                                ABOUT THIS FILE
        This file contains routines which communicate with the NetROM.  To
    be able to send and receive characters, target-side programmers need
    only port the clearly marked section at the top of the file.  A hook
    is provided for tasking systems which need to allow processes to run;
    this is the YIELD_CPU macro.  The routine c_dpcons_hdlr() handles
    receipt of messages from the NetROM.  Since the NetROM cannot cause
    target-side interrupts, it is called when the target checks for data.
        The entry points that the target programmer needs to use are:
            config_dpram        initializes control structures and configures
                        the target to use dualport in a read-only or read-
                        write fashion.
            set_dp_blockio      allows the target programmer to set or
                        clear a bit in the control structure.  When set,
                        the interface routines merely poll for data and
                        return if none is present.  Otherwise they will
                        wait for data to appear.
            dp_chanready        returns 1 if the NetROM is ready to
                        process messages; 0 otherwise.
	    chan_kbhit		returns 1 if a character is waiting at the 
			dualport interface; 0 otherwise.
            ra_putch            sends a character to the NetROM using the
                        read-address interface.  This routine handles all
                        of the appropriate software handshaking.
            chan_putch          sends a character to the NetROM.  Actually,
                        it stores characters until the message structure is
                        full or chan_flushtx() is called.  This reduces
                        protocol overhead.
            chan_flushtx        sends any characters which have been stored
                        but not yet passed to the NetROM.
            ra_getch            reads a character from the NetROM, if one
                        is present, using the RX message structures of the 
			read-address protocol.
            chan_getch          reads a character from the NetROM, if one
                        is present, using the RX message structures of the
			readwrite protocol.
	    ra_getmsg		reads a message from dualport ram, when using
			the read-address protocol.
	    chan_getmsg		reads a message from dualport ram, when using
			the readwrite protocol.
	    ra_putmsg		sends a complete message delineated by the 
			START and END out-of-band characters.
	    chan_putmsg		sends a complete message delineated by the
	    		START and END bits in the dualport message structures.
			This differs from the ra_putch() routine, which treats
			each dualport message structure as a complete
			message.
	    ra_setmem		requests that NetROM write a byte of 
			emulation memory.
			if ra_emoffonwrite has been called, emulation memory is
			turned off before the byte is written.
	    ra_reset		requests that NetROM reset the target.	
            ra_resync		requests that NetROM re-initialize  it's 
			dualport parameters.
	    ra_rx_intr_ack	acknowledges a receive interrupt
	    ra_emoffonwrite	see ra_setmem

	Note that the getmsg() routines are used to incrementally fill an
    input buffer.  When used in a polling mode, they return one of four 
    status values:  GM_NODATA indicates that no data has arrived since the
    last poll; GM_MSGCOMPLETE indicates that new data has arrived and that the
    input buffer now holds the complete message; GM_NOTDONE indicates that
    data has arrived but that the message is not yet complete; GM_MSGOVERFLOW
    indicates that more data has arrived, but that it has overflown the input
    buffer.  In a non-polling mode, these routines will return either
    GM_MSGCOMPLETE or GM_MSGOVERFLOW.

*********************************************************************/
/* Local Defines */
#define DUMMY_READ

#include "wdb/dpconfig.h"     /* This file must be ported to the new target */
#include "wdb/dptarget.h"	     
#include "wdb/dualport.h"
#include "stdio.h"


/* declarations */
STATIC void c_dpcons_hdlr();
void chan_flushtx();
void set_dp_blockio();
void ra_putch();
int do_emoffonwrite();

/* global data */
STATIC DpChannel channels[DP_MAXCHANNELS];

#ifdef READONLY_TARGET
STATIC int emoffonwrite_set;
#endif


#ifndef RAWRITES_ONLY
STATIC uInt16 dp_readint();
void dp_bwrite();
void dp_bread();

#ifndef	READONLY_TARGET
/* writes an int to dp ram */
STATIC void
dp_writeint(addr,val)
uInt32 addr;
uInt16 val;
{	

    /* write in network byte order, lsb first */
    WRITE_POD(&channels[0], addr + 1, (uInt32)val & 0xFF);
    WRITE_POD(&channels[0], addr, (uInt32)(val >> 8) & 0xFF);

    /* Check that the write was sucessful.  See change log dated 8/21/95
       at the top of this file for details. */
    while (val != dp_readint(addr)) {
        WRITE_POD(&channels[0], addr + 1, (uInt32)val & 0xFF);
        WRITE_POD(&channels[0], addr, (uInt32)(val >> 8) & 0xFF);
    }
}
#endif

/* read an int from dpram */
STATIC uInt16
dp_readint(addr)
uInt32 addr;
{
    uInt16 val;

    /* read the msb first, in case it contains flags */