shm_driver.h

RTEMS (Real-Time Executive for Multiprocessor Systems) is a free open source real-time operating sys

/*  shm_driver.h
 *
 *  This include file contains all the constants, structures,
 *  and global variables for this RTEMS based shared memory
 *  communications interface driver.
 *
 *  Processor board dependencies are in other files.
 *
 *  COPYRIGHT (c) 1989-1999.
 *  On-Line Applications Research Corporation (OAR).
 *
 *  The license and distribution terms for this file may be
 *  found in the file LICENSE in this distribution or at
 *  http://www.rtems.com/license/LICENSE.
 *
 *  $Id: shm_driver.h,v 1.19.6.2 2006/04/24 18:45:03 joel Exp $
 */

#ifndef __SHM_h
#define __SHM_h

#include <clockdrv.h>

#ifdef __cplusplus
extern "C" {
#endif

/*  The information contained in the Node Status, Locked Queue, and
 *  Envelope Control Blocks must be maintained in a NEUTRAL format.
 *  Currently the neutral format may be selected as big or little
 *  endian by simply defining either NEUTRAL_BIG or NEUTRAL_LITTLE.
 *
 *  It is CRITICAL to note that the neutral format can ONLY be
 *  changed by modifying this file and recompiling the ENTIRE
 *  SHM driver including ALL target specific support files.
 *
 *  The following table details the memory contents for the endian
 *  field of the Node Status Control Block in the various
 *  data format configurations (data is in hexadecimal):
 *
 *   NEUTRAL NATIVE BYTE 0  BYTE 1  BYTE 2  BYTE 3
 *   ======= ====== ======  ======  ======  ======
 *    BIG     BIG     00      00      00      01
 *    BIG    LITTLE   10      00      00      00
 *   LITTLE   BIG     01      00      00      00
 *   LITTLE  LITTLE   00      00      00      10
 *
 *
 *  NOTE: XXX
 *                PORTABILITY OF LOCKING INSTRUCTIONS
 *                ===================================
 *            The locking mechanism described below is not
 *            general enough.  Where the hardware supports
 *            it we should use "atomic swap" instructions
 *            so the values in the lock can be tailored to
 *            support a CPU with only weak atomic memory
 *            instructions.  There are combinations of
 *            CPUs with inflexible atomic memory instructions
 *            which appear to be incompatible.  For example,
 *            the SPARClite instruction uses a byte which is
 *            0xFF when locked.  The PA-RISC uses 1 to indicate
 *            locked and 0 when unlocked.  These CPUs appear to
 *            have incompatible lock instructions.  But
 *            they could be used in a heterogenous system
 *            with does not mix SPARCs and PA-RISCs.  For
 *            example, the i386 and SPARC or i386 and SPARC
 *            could work together.  The bottom line is that
 *            not every CPU will work together using this
 *            locking scheme.  There are supposed to be
 *            algorithms to do this without hardware assist
 *            and one of these should be incorporated into
 *            the shared memory driver.
 *
 *            The most flexible scheme using the instructions
 *            of the various CPUs for efficiency would be to use
 *            "atomic swaps" wherever possible.  Make the lock
 *            and unlock configurable much like BIG vs LITTLE
 *            endian use of shared memory is now.  The values
 *            of the lock could then reflect the "worst"
 *            CPU in a system.  This still results in mixes
 *            of CPUs which are incompatible.
 *
 *  The current locking mechanism is based upon the MC68020
 *  "tas" instruction which is atomic.  All ports to other CPUs
 *  comply with the restrictive placement of lock bit by this
 *  instruction.  The lock bit is the most significant bit in a
 *  big-endian rtems_unsigned32.  On other processors, the lock is
 *  typically implemented via an atomic swap or atomic modify
 *  bits type instruction.
 */

#define NEUTRAL_BIG

#ifdef NEUTRAL_BIG
#define SHM_BIG       0x00000001
#define SHM_LITTLE    0x10000000
#endif

#ifdef NEUTRAL_LITTLE
#define SHM_BIG       0x01000000
#define SHM_LITTLE    0x00000010
#endif

/*
 *  The following are the values used to fill in the lock field.  Some CPUs
 *  are able to write only a single value into field.  By making the
 *  lock and unlock values configurable, CPUs which support "atomic swap"
 *  instructions can generally be made to work in any heterogeneous
 *  configuration.  However, it is possible for two CPUs to be incompatible
 *  in regards to the lock field values.  This occurs when two CPUs
 *  which write only a single value to the field are used in a system
 *  but the two CPUs write different incompatible values.
 *
 *  NOTE:  The following is a first attempt at defining values which
 *         have a chance at working together.  The m68k should use
 *         chk2 instead of tas to be less restrictive.  Target endian
 *         problems (like the Force CPU386 which has (broken) big endian
 *         view of the VMEbus address space) are not addressed yet.
 */

#if defined(__i960__)
#define SHM_LOCK_VALUE    0x00000080
#define SHM_UNLOCK_VALUE  0
#elif defined(__mc68000__)
#define SHM_LOCK_VALUE    0x80000000
#define SHM_UNLOCK_VALUE  0
#define SHM_LOCK_VALUE    0x80000000
#define SHM_UNLOCK_VALUE  0
#elif defined(__i386__)
#define SHM_LOCK_VALUE    0x80000000
#define SHM_UNLOCK_VALUE  0
#elif defined(__mips__)
#define SHM_LOCK_VALUE    0x80000000
#define SHM_UNLOCK_VALUE  0
#elif defined(__hppa__)
#define SHM_LOCK_VALUE    0
#define SHM_UNLOCK_VALUE  1
#elif defined(__PPC__)
#define SHM_LOCK_VALUE    1
#define SHM_UNLOCK_VALUE  0
#elif defined(__unix__)
#define SHM_LOCK_VALUE    0
#define SHM_UNLOCK_VALUE  1
#elif defined(_AM29K)
#define SHM_LOCK_VALUE    0
#define SHM_UNLOCK_VALUE  1
#elif defined(__sparc__)
#define SHM_LOCK_VALUE    1
#define SHM_UNLOCK_VALUE  0
#elif defined(no_cpu)               /* for this values are irrelevant */
#define SHM_LOCK_VALUE    1
#define SHM_UNLOCK_VALUE  0
#else
#error "shm_driver.h - no SHM_LOCK_VALUE defined for this CPU architecture"
#endif

#define Shm_Convert( value ) \
  ((Shm_Configuration->convert) ? \
    (*Shm_Configuration->convert)(value) : (value))

/* constants */

#define SHM_MASTER                  1     /* master initialization node */
#define SHM_FIRST_NODE              1

/* size constants */

#define KILOBYTE          (1024)
#define MEGABYTE          (1024*1024)

/* inter-node interrupt values */

#define NO_INTERRUPT            0     /* used for polled nodes */
#define BYTE                    1
#define WORD                    2
#define LONG                    4

/* operational mode constants -- used in SHM Configuration Table */
#define POLLED_MODE             0
#define INTR_MODE               1

/* error codes */

#define NO_ERROR                0
#define SHM_NO_FREE_PKTS        0xf0000

/* null pointers of different types */

#define NULL_ENV_CB             ((Shm_Envelope_control *) 0)
#define NULL_CONVERT            0

/*
 * size of stuff before preamble in envelope.
 * It must be a constant since we will use it to generate MAX_PACKET_SIZE
 */
 
#define SHM_ENVELOPE_PREFIX_OVERHEAD    (4 * sizeof(vol_u32))

/*
 *  The following is adjusted so envelopes are MAX_ENVELOPE_SIZE bytes long.
 *  It must be >= RTEMS_MINIMUM_PACKET_SIZE in mppkt.h.
 */
 
#ifndef MAX_ENVELOPE_SIZE
#define MAX_ENVELOPE_SIZE 0x180
#endif

#define MAX_PACKET_SIZE  (MAX_ENVELOPE_SIZE -               \
                          SHM_ENVELOPE_PREFIX_OVERHEAD +    \
                          sizeof(Shm_Envelope_preamble) +   \
                          sizeof(Shm_Envelope_postamble))


/* constants pertinent to Locked Queue routines */

#define LQ_UNLOCKED              SHM_UNLOCK_VALUE
#define LQ_LOCKED                SHM_LOCK_VALUE

/* constants related to the Free Envelope Pool */

#define FREE_ENV_POOL            0
#define FREE_ENV_CB              (&Shm_Locked_queues[ FREE_ENV_POOL ])

/*  The following are important when dealing with
 *  the shared memory communications interface area.
 *
 *  NOTE: The starting address and length of the shared memory
 *        is defined in a system dependent file.
 */

#define START_NS_CBS     ((void *)Shm_Configuration->base)
#define START_LQ_CBS     ((START_NS_CBS) + \
        ( (sizeof (Shm_Node_status_control)) * (Shm_Maximum_nodes + 1) ) )
#define START_ENVELOPES  ( ((void *) START_LQ_CBS) + \
        ( (sizeof (Shm_Locked_queue_Control)) * (Shm_Maximum_nodes + 1) ) )
#define END_SHMCI_AREA    ( (void *) START_ENVELOPES + \
        ( (sizeof (Shm_Envelope_control)) * Shm_Maximum_envelopes ) )
#define END_SHARED_MEM   (START_NS_CBS+Shm_Configuration->length)

/* macros */

#define Shm_Is_master_node()  \
  ( SHM_MASTER == Shm_Local_node )

#define Shm_Free_envelope( ecb ) \
  Shm_Locked_queue_Add( FREE_ENV_CB, (ecb) )
#define Shm_Allocate_envelope() \
  Shm_Locked_queue_Get(FREE_ENV_CB)

#define Shm_Initialize_receive_queue(node) \
  Shm_Locked_queue_Initialize( &Shm_Locked_queues[node], node )

#define Shm_Append_to_receive_queue(node, ecb) \
  Shm_Locked_queue_Add( &Shm_Locked_queues[node], (ecb) )

#define Shm_Envelope_control_to_packet_prefix_pointer(ecb)  \
   ((void *)(ecb)->packet)

#define Shm_Packet_prefix_to_envelope_control_pointer( pkt )   \
   ((Shm_Envelope_control *)((rtems_unsigned8 *)(pkt) - \
   (sizeof(Shm_Envelope_preamble) + SHM_ENVELOPE_PREFIX_OVERHEAD)))

#define Shm_Build_preamble(ecb, node) \
       (ecb)->Preamble.endian = Shm_Configuration->format

#define Shm_Build_postamble( ecb )

/* volatile types */

typedef volatile rtems_unsigned8  vol_u8;
typedef volatile rtems_unsigned32 vol_u32;

/* shm control information */