Subversion Repositories or1k

@c

@c  COPYRIGHT (c) 1988-2002.

@c  On-Line Applications Research Corporation (OAR).

@c  All rights reserved.

@c

@c  shmsupp.t,v 1.5 2002/01/17 21:47:44 joel Exp

@c

@chapter Shared Memory Support Driver

The Shared Memory Support Driver is responsible for providing glue

routines and configuration information required by the Shared

Memory Multiprocessor Communications Interface (MPCI).  The

Shared Memory Support Driver tailors the portable Shared

Memory Driver to a particular target platform.

This driver is only required in shared memory multiprocessing

systems that use the RTEMS mulitprocessing support.  For more

information on RTEMS multiprocessing capabilities and the

MPCI, refer to the @b{Multiprocessing Manager} chapter

of the @b{RTEMS Application C User's Guide}.

@section Shared Memory Configuration Table

The Shared Memory Configuration Table is defined in the following

structure:

@example

@group

typedef volatile rtems_unsigned32 vol_u32;

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;

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;

@end group

@end example

where the fields are defined as follows:

@table @b

@item base

is the base address of the shared memory buffer used to pass

messages between the nodes in the system.

@item length

is the length (in bytes) of the shared memory buffer used to pass

messages between the nodes in the system.

@item format

is either SHM_BIG or SHM_LITTLE to indicate that the neutral format

of the shared memory area is big or little endian.  The format

of the memory should be chosen to match most of the inter-node traffic.

@item convert

is the address of a routine which converts from native format to

neutral format.   Ideally, the neutral format is the same as the

native format so this routine is quite simple.

@item poll_intr

is either INTR_MODE or POLLED_MODE to indicate how the node will be

informed of incoming messages.

@item cause_intr

@item Intr

is the information required to cause an interrupt on a node.  This

structure contains the following fields:

@table @b

@item address

is the address to write at to cause an interrupt on that node.

For a polled node, this should be NULL.

@item value

is the value to write to cause an interrupt.

@item length

is the length of the entity to write on the node to cause an interrupt.

This can be 0 to indicate polled operation, 1 to write a byte, 2 to

write a sixteen-bit entity, and 4 to write a thirty-two bit entity.

@end table

@end table

@section Primitives

@subsection Convert Address

The @code{Shm_Convert_address} is responsible for converting an address

of an entity in the shared memory area into the address that should be

used from this node.  Most targets will simply return the address

passed to this routine.  However, some target boards will have a special

window onto the shared memory.  For example, some VMEbus boards have

special address windows to access addresses that are normally reserved

in the CPU's address space.

@example

@group

void *Shm_Convert_address( void *address )

@{

   return the local address version of this bus address

@}

@end group

@end example

@subsection Get Configuration

The @code{Shm_Get_configuration} routine is responsible for filling in the

Shared Memory Configuration Table passed to it.

@example

@group

void Shm_Get_configuration(

  rtems_unsigned32   localnode,

  shm_config_table **shmcfg

)

@{

   fill in the Shared Memory Configuration Table

@}

@end group

@end example

@subsection Locking Primitives

This is a collection of routines that are invoked by the portable

part of the Shared Memory Driver to manage locks in the shared

memory buffer area.  Accesses to the shared memory must be

atomic.  Two nodes in a multiprocessor system must not be manipulating

the shared data structures simultaneously.  The locking primitives

are used to insure this.

To avoid deadlock, local processor interrupts should be disabled the entire

time the locked queue is locked.

The locking primitives operate on the lock

@code{field} of the @code{Shm_Locked_queue_Control}

data structure.  This structure is defined as follows:

@example

@group

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;

@end group

@end example

where each field is defined as follows:

@table @b

@item lock

is the lock field.  Every node in the system must agree on how this

field will be used.  Many processor families provide an atomic

"test and set" instruction that is used to manage this field.

@item front

is the index of the first message on this locked queue.

@item rear

is the index of the last message on this locked queue.

@item owner

is the node number of the node that currently has this structure locked.

@end table

@subsubsection Initializing a Shared Lock

The @code{Shm_Initialize_lock} routine is responsible for

initializing the lock field.  This routines usually is implemented

as follows:

@example

@group

void Shm_Initialize_lock(

  Shm_Locked_queue_Control *lq_cb

)

@{

  lq_cb->lock = LQ_UNLOCKED;

@}

@end group

@end example

@subsubsection Acquiring a Shared Lock

The @code{Shm_Lock} routine is responsible for

acquiring the lock field.  Interrupts should be

disabled while that lock is acquired.  If the lock

is currently unavailble, then the locking routine

should delay a few microseconds to allow the other

node to release the lock.  Doing this reduces bus contention

for the lock.  This routines usually is implemented as follows:

@example

@group

void Shm_Lock(

  Shm_Locked_queue_Control *lq_cb

)

@{

  disable processor interrupts

    set Shm_isrstat to previous interrupt disable level

    while ( TRUE ) @{

      atomically attempt to acquire the lock

      if the lock was acquired

        return

      delay some small period of time

    @}

@}

@end group

@end example

@subsubsection Releasing a Shared Lock

The @code{Shm_Unlock} routine is responsible for

releasing the lock field and reenabling processor

interrupts.  This routines usually is implemented as follows:

@example

@group

void Shm_Unlock(

  Shm_Locked_queue_Control *lq_cb

)

@{

  set the lock to the unlocked value

  reenable processor interrupts to their level prior

    to the lock being acquired.  This value was saved

    in the global variable Shm_isrstat

@}

@end group

@end example

@section Installing the MPCI ISR

The @code{Shm_setvec} is invoked by the portable portion

of the shared memory to install the interrupt service routine

that is invoked when an incoming message is announced.  Some

target boards support an interprocessor interrupt or mailbox

scheme and this is where the ISR for that interrupt would be

installed.

On an interrupt driven node, this routine would be implemented

as follows:

@example

@group

void Shm_setvec( void )

@{

  install the interprocessor communications ISR

@}

@end group

@end example

On a polled node, this routine would be empty.