shm_driver.h

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

struct shm_info {
  vol_u32 not_currently_used_0;
  vol_u32 not_currently_used_1;
  vol_u32 not_currently_used_2;
  vol_u32 not_currently_used_3;
};

typedef struct {
  /*byte start_of_text;*/
  vol_u32 endian;
  vol_u32 not_currently_used_0;
  vol_u32 not_currently_used_1;
  vol_u32 not_currently_used_2;
} Shm_Envelope_preamble;

typedef struct {
} Shm_Envelope_postamble;

/* WARNING! If you change this structure, don't forget to change
 *          SHM_ENVELOPE_PREFIX_OVERHEAD and
 *          Shm_Packet_prefix_to_envelope_control_pointer() above.
 */

/*  This comment block describes the contents of each field
 *  of the Envelope Control Block:
 *
 *  next      - The index of the next envelope on this queue.
 *  queue     - The index of the queue this envelope is on.
 *  index     - The index of this envelope.
 *  Preamble  - Generic packet preamble.  One day this structure
 *              could be enhanced to contain routing information.
 *  packet    - RTEMS MPCI packet.  Untouched by SHM Driver
 *              other than copying and format conversion as
 *              documented in the RTEMS User's Guide.
 *  Postamble - Generic packet postamble.  One day this structure
 *              could be enhanced to contain checksum information.
 */

typedef struct {
  vol_u32           next;     /* next envelope on queue       */
  vol_u32           queue;    /* queue on which this resides  */
  vol_u32           index;    /* index into array of envelopes*/
  vol_u32           pad0;     /* insure the next one is aligned */
  Shm_Envelope_preamble    Preamble; /* header information           */
  vol_u8            packet[MAX_PACKET_SIZE]; /* RTEMS INFO    */
  Shm_Envelope_postamble   Postamble;/* trailer information          */
} Shm_Envelope_control;

/*  This comment block describes the contents of each field
 *  of the Locked Queue Control Block:
 *
 *  lock      - Lock used to insure mutually exclusive access.
 *  front     - Index of first envelope on queue.  This field
 *              is used to remove head of queue (receive).
 *  rear      - Index of last envelope on queue.  This field
 *              is used to add evelope to queue (send).
 *  owner     - The node number of the recipient (owning) node.
 *              RTEMS does not use the node number zero (0).
 *              The zero node is used by the SHM Driver for the
 *              Free Envelope Queue shared by all nodes.
 */

typedef struct {
  vol_u32 lock;  /* lock field for this queue    */
  vol_u32 front; /* first envelope on queue      */
  vol_u32 rear;  /* last envelope on queue       */
  vol_u32 owner; /* receiving (i.e. owning) node */
} Shm_Locked_queue_Control;

/*  This comment block describes the contents of each field
 *  of the Node Status Control Block:
 *
 *  status    - Node status.  Current values are Pending Initialization,
 *              Initialization Complete, and Active Node.  Other values
 *              could be added to enhance fault tolerance.
 *  error     - Zero if the node has not failed.  Otherwise,
 *              this field contains a status indicating the
 *              failure reason.
 *  int_address, int_value, and int_length
 *            - These field are the Interrupt Information table
 *              for this node in neutral format.  This is how
 *              each node knows how to generate interrupts.
 */

typedef struct {
  vol_u32  status;         /* node status information     */
  vol_u32  error;          /* fatal error code            */
  vol_u32  int_address;    /* write here for interrupt    */
  vol_u32  int_value;      /* this value causes interrupt */
  vol_u32  int_length;     /* for this length (0,1,2,4)   */
  vol_u32  not_currently_used_0;
  vol_u32  not_currently_used_1;
  vol_u32  not_currently_used_2;
} Shm_Node_status_control;

/*  This comment block describes the contents of each field
 *  of the Interrupt Information Table.  This table describes
 *  how another node can generate an interrupt to this node.
 *  This information is target board dependent.  If the
 *  SHM Driver is in POLLED_MODE, then all fields should
 *  be initialized to NO_INTERRUPT.
 *
 *  address   - The address to which another node should
 *              write to cause an interrupt.
 *  value     - The value which must be written
 *  length    - The size of the value to write.  Valid
 *              values are BYTE, WORD, and LONG.
 *
 *  NOTE:  The Node Status Control Block contains this
 *         information in neutral format and not in a
 *         structure to avoid potential alignment problems.
 */

typedef struct {
  vol_u32 *address;        /* write here for interrupt    */
  vol_u32  value;          /* this value causes interrupt */
  vol_u32  length;         /* for this length (0,1,2,4)   */
} Shm_Interrupt_information;

/*  SHM Configuration Table
 *
 *  This comment block describes the contents of each field
 *  of the SHM Configuration Table.
 *
 *  base       - The base address of the shared memory.  This
 *               address may be specific to this node.
 *  length     - The length of the shared memory in bytes.
 *  format     - The natural format for rtems_unsigned32's in the
 *               shared memory.  Valid values are currently
 *               only SHM_LITTLE and SHM_BIG.
 *  convert    - The address of the routine which converts
 *               between neutral and local format.
 *  poll_intr  - The operational mode of the driver.  Some
 *               target boards may not provide hardware for
 *               an interprocessor interrupt.  If POLLED_MODE
 *               is selected, the SHM driver will install a
 *               wrapper around the Clock_isr() to poll for
 *               incoming packets.  Throughput is dependent
 *               on the time between clock interrupts.
 *               Valid values are POLLED_MODE and INTR_MODE.
 *  cause_intr - This is the address of the routine used to
 *               write to a particular address and cause an
 *               interrupt on another node.  This routine
 *               may need to be target dependent if something
 *               other than a normal write from C does not work.
 *  Intr       - This structure describes the operation required
 *               to cause an interrupt to this node.  The actual
 *               contents of this structure are described above.
 */

struct shm_config_info {
  vol_u32           *base;     /* base address of SHM         */
  vol_u32            length;   /* length (in bytes) of SHM    */
  vol_u32            format;   /* SHM is big or little endian */
  vol_u32          (*convert)();/* neutral conversion routine */
  vol_u32            poll_intr;/* POLLED or INTR driven mode  */
  void             (*cause_intr)( rtems_unsigned32 );
  Shm_Interrupt_information   Intr;     /* cause intr information      */
};

typedef struct shm_config_info shm_config_table;

/* global variables */

#ifdef _SHM_INIT
#define SHM_EXTERN
#else
#define SHM_EXTERN extern
#endif

SHM_EXTERN shm_config_table             *Shm_Configuration;
SHM_EXTERN Shm_Interrupt_information    *Shm_Interrupt_table;
SHM_EXTERN Shm_Node_status_control      *Shm_Node_statuses;
SHM_EXTERN Shm_Locked_queue_Control     *Shm_Locked_queues;
SHM_EXTERN Shm_Envelope_control         *Shm_Envelopes;
SHM_EXTERN rtems_configuration_table    *Shm_RTEMS_Configuration;
SHM_EXTERN rtems_multiprocessing_table  *Shm_RTEMS_MP_Configuration;
SHM_EXTERN rtems_unsigned32              Shm_Receive_message_count;
SHM_EXTERN rtems_unsigned32              Shm_Null_message_count;
SHM_EXTERN rtems_unsigned32              Shm_Interrupt_count;
SHM_EXTERN rtems_unsigned32              Shm_Local_node;
SHM_EXTERN Shm_Locked_queue_Control      *Shm_Local_receive_queue;
SHM_EXTERN Shm_Node_status_control       *Shm_Local_node_status;
SHM_EXTERN rtems_unsigned32              Shm_isrstat;
                                                     /* reported by shmdr */

SHM_EXTERN rtems_unsigned32 Shm_Pending_initialization;
SHM_EXTERN rtems_unsigned32 Shm_Initialization_complete;
SHM_EXTERN rtems_unsigned32 Shm_Active_node;

SHM_EXTERN rtems_unsigned32 Shm_Maximum_nodes;
SHM_EXTERN rtems_unsigned32 Shm_Maximum_envelopes;

SHM_EXTERN rtems_unsigned32 Shm_Locked_queue_End_of_list;
SHM_EXTERN rtems_unsigned32 Shm_Locked_queue_Not_on_list;

/* functions */

/* locked queue routines */
void           Shm_Locked_queue_Add(
                  Shm_Locked_queue_Control *, Shm_Envelope_control * );
Shm_Envelope_control *Shm_Locked_queue_Get( Shm_Locked_queue_Control * );
void           Shm_Locked_queue_Initialize(
                  Shm_Locked_queue_Control *, rtems_unsigned32 );
            /* Shm_Initialize_lock is CPU dependent */
            /* Shm_Lock is CPU dependent */
            /* Shm_Unlock is CPU dependent */

/* portable routines */
void           Init_env_pool();
void           Shm_Print_statistics( void );
void           MPCI_Fatal( Internal_errors_Source, boolean, rtems_unsigned32 );
rtems_task     Shm_Cause_interrupt( rtems_unsigned32 );
void           Shm_Poll();
void           Shm_setclockvec();
void           Shm_Convert_packet( rtems_packet_prefix * );

/* CPU specific routines are inlined in shmcpu.h */

/* target specific routines */
void          *Shm_Convert_address( void * );
void           Shm_Get_configuration( rtems_unsigned32, shm_config_table ** );
void           Shm_isr();
void           Shm_setvec( void );

void           Shm_Initialize_lock( Shm_Locked_queue_Control * );
void           Shm_Lock( Shm_Locked_queue_Control * );
void           Shm_Unlock( Shm_Locked_queue_Control * );

/* MPCI entry points */
rtems_mpci_entry Shm_Get_packet(
  rtems_packet_prefix **
);

rtems_mpci_entry Shm_Initialization( void );

rtems_mpci_entry Shm_Receive_packet(
  rtems_packet_prefix **
);

rtems_mpci_entry Shm_Return_packet(
  rtems_packet_prefix *
);

rtems_mpci_entry Shm_Send_packet(
  rtems_unsigned32,
  rtems_packet_prefix *
);

extern rtems_mpci_table MPCI_table;

#ifdef _SHM_INIT

/* multiprocessor communications interface (MPCI) table */

rtems_mpci_table MPCI_table  = {
  100000,                     /* default timeout value in ticks */
  MAX_PACKET_SIZE,            /* maximum packet size */
  Shm_Initialization,         /* initialization procedure   */
  Shm_Get_packet,             /* get packet procedure       */
  Shm_Return_packet,          /* return packet procedure    */
  Shm_Send_packet,            /* packet send procedure      */
  Shm_Receive_packet          /* packet receive procedure   */
};

#endif

#ifdef __cplusplus
}
#endif

#endif
/* end of include file */