---

UNIV.c File Reference

Universe II Utilities, Interface. More...

#include <vxWorks.h>
#include <sysLib.h>
#include <intLib.h>
#include <iv.h>
#include "MV2X/mv2600.h"
#include "./universe.h"
#include "UNIV_vxworks.h"
#include "BVME/UNIV.h"
#include "BBC/BSWP.ih"

Defines
#define	UNIV_A_DGCS   (volatile unsigned int *)UNIVERSE_DGCS
	Address of General Control/Status Register.
#define	UNIV_A_DCPP   (volatile unsigned int *)UNIVERSE_DCPP
	Address of Command Packet Pointer Register.
#define	UNIV_A_DTBC   (volatile unsigned int *)UNIVERSE_DTBC
	Address of Transfer Byte Count Register.
#define	UNIV_A_PCI_CSR   (volatile unsigned int *)UNIVERSE_PCI_CSR
	Address of PCI CSR Register.
#define	UNIV_A_LINT_EN   (volatile unsigned int *)UNIVERSE_LINT_EN
	Address of LINT Enable (PCI interrupt).
#define	UNIV_A_LINT_STAT   (volatile unsigned int *)UNIVERSE_LINT_STAT
	Addesss of LINT Status Register.
#define	DGCS_ERRMSK   (DGCS_LERR | DGCS_VERR | DGCS_P_ERR)
	Error status bits.
#define	DGCS_STATUS   (DGCS_ACT | DGCS_DONE | DGCS_ERRMSK)
	Success Status bits.
#define	eieio   asm volatile ("eieio"::)
	Drops an eieio instruction.
Functions
unsigned int	readReg (volatile unsigned int *adr)
	Internal function to read a 32 PCI address, with eieio synch. More...
unsigned int	mreadReg (volatile unsigned int *adr)
	Internal function to read a 32 PCI address, no eieio synch. More...
unsigned int	bclrReg (volatile unsigned int *adr, unsigned int clrMsk)
	Clears the specified bits. More...
unsigned int	bmodReg (volatile unsigned int *adr, unsigned int modMsk, unsigned int val)
	Modifies a selected set of bits. More...
unsigned int	bsetReg (volatile unsigned int *adr, unsigned int setMsk)
	Sets the specified bits. More...
void	writeReg (volatile unsigned int *adr, unsigned int value)
	Internal function to write a 32 PCI address, with eieio synch. More...
void	mwriteReg (volatile unsigned int *adr, unsigned int value)
	Internal function to write a 32 PCI address, no eieio synch. More...
unsigned int	readDGCS (void)
	Reads the DGCS register. More...
unsigned int	bclrDGCS (unsigned int bitsToClr)
	Clears the specified bits in the DGCS register. More...
unsigned int	bmodDGCS (unsigned int bitsToMod, unsigned int value)
	Modifies a selected set of bits in the DGCS register. More...
unsigned int	bsetDGCS (unsigned int bitsToClr)
	Sets the specified bits in the DGCS register. More...
void	writeDGCS (unsigned int value)
	Writes the DGCS register. More...
_UNIV_dcp *	UNIV_DCPP_read (void)
	Reads the DCPP register, (Command Packet Pointer). More...
void	UNIV_DCPP_write (const struct _UNIV_dcp *dcpp)
	Write the DCPP register with the head of a DMA linked list. More...
unsigned int	UNIV_DTBC_read (void)
	Reads the DTBC register, (Transfer Byte Count). More...
void	UNIV_DTBC_write (unsigned int byteCount)
	Writes the DTBC register, (Transfer Byte Count). More...
unsigned int	UNIV_DGCS_read (void)
	Reads the DGCS register, (General Control/Status Register. More...
unsigned int	UNIV_DGCS_bclr (unsigned int bitsToClr)
	Clears the specified bits in the DGCS register, (General Control/Status Register). More...
unsigned int	UNIV_DGCS_bmod (unsigned int bitsToMod, unsigned int value)
	Modifies a selected set of bits in the DGCS register. More...
unsigned int	UNIV_DGCS_bset (unsigned int bitsToSet)
	Sets the specified bits in the DGCS register. More...
void	UNIV_DGCS_write (unsigned int value)
	Writes the DGCS register, (General Control/Status Register). More...
unsigned int	UNIV_go (void)
	Initiates a start on on a DMA operation by hitting to GO bit in the DGCS register. More...
unsigned int	UNIV_request_halt (void)
	Request a halt on an ongoing DMA operation. More...
unsigned int	UNIV_request_stop (void)
	Request a stop on an ongoing DMA operation. More...
void	UNIV_go_at (struct _UNIV_dcp *head)
	This initiates a chain UNIV transfer by the Universe at the specified command head. More...
void	UNIV_dcp_array_init (struct _UNIV_dcp *dcpp, int cnt)
	Initializes an array of Universe DMA Command packets to form a circular list. Only the link field is filled in. More...
void	UNIV_dcp_complete (struct _UNIV_dcp *dcpp, unsigned int dctl, unsigned int vmeAdr, unsigned char *lclAdr, int nbytes)
	Complete the DMA Command Packet, ie finishes the job UNIV_dcp_array_init started. More...
int	UNIV_int_connect (unsigned int which, UNIV_isr routine, void *parameter)
	Connects a ISR routine to service the UNIVERSET II interrupts. More...
int	UNIV_int_disable (void)
	Disables delivery of interrupts from the UNIVERSE II. More...
int	UNIV_int_enable ()
	Enables delivery of interrupts from the UNIVERSE II. More...
unsigned int	UNIV_bus_master_set (void)
	Ensures the UNIVERSE II is a PCI bus master. More...

---

Detailed Description

Universe II Utilities, Interface.

Author:

JJRussell - russell@slac.stanford.edu

---

Function Documentation

unsigned int bclrDGCS (  unsigned int    clrMsk )  [inline, static]

Clears the specified bits in the DGCS register. Parameters: clrMsk  A mask of bits to clear, bits set to 1 will be cleared. Returns: The original value before clearing. Clears the specified bits. This implements the following pseudocode *adr &= ~clrMsk; Warning: This is not done in an indivisible manner.

unsigned int bclrReg (  volatile unsigned int *    adr, unsigned int    clrMsk )  [inline, static]

Clears the specified bits. Parameters: adr  The address to clear the bits in. clrMsk  The clear mask. Bits set to 1 are cleared. Returns: The original value before the bits are cleared. Clears the specified bits. This implements the following pseudocode *adr &= ~clrMsk; Warning: This is not done in an indivisible manner.

unsigned int bmodDGCS (  unsigned int    mod, unsigned int    val )  [inline, static]

Modifies a selected set of bits in the DGCS register. Parameters: modMsk  Which bits to modify. value  The new values. Returns: The original value before modification. Warning: This is not done in an indivisible manner.

unsigned int bmodReg (  volatile unsigned int *    adr, unsigned int    modMsk, unsigned int    value )  [inline, static]

Modifies a selected set of bits. Parameters: adr  The PCI address to modify. modMsk  Which bits to modify. value  The new values. Returns: The original value before modification. Function to consolidate the setting of individual fields of a PCI memory location. Warning: This is not done in an indivisible manner.

unsigned int bsetDGCS (  unsigned int    set )  [inline, static]

Sets the specified bits in the DGCS register. Parameters: setMsk  The set mask. Bits set to 1 are set. Returns: The original value before the bits are set. Sets the specified bits. This implements the following pseudocode *adr |= setMsk; Warning: This is not done in an indivisible manner.

unsigned int bsetReg (  volatile unsigned int *    adr, unsigned int    setMsk )  [inline, static]

Sets the specified bits. Parameters: adr  The PCI address to set the bits in. setMsk  The set mask. Bits set to 1 are set. Returns: The original value before the bits are set. Sets the specified bits. This implements the following pseudocode *adr |= setMsk; Warning: This is not done in an indivisible manner.

unsigned int mreadReg (  volatile unsigned int *    adr )  [inline, static]

Internal function to read a 32 PCI address, no eieio synch. Parameters: The  local address to read. Returns: The read value. Function to consolidate the method of reading of a 32bit PCI address. This form is a minimal read, not using the EIEIO instruction.

void mwriteReg (  volatile unsigned int *    adr, unsigned int    value )  [inline, static]

Internal function to write a 32 PCI address, no eieio synch. Parameters: adr  The local address to write. value  The value to write. Function to consolidate writing of a 32bit PCI address with a known value. This is done so that any common error checking code can be inserted here. This form is the minimal write, not using the EIEIO instruction to ensure in order reads and writes.

unsigned int readDGCS (  void    )  [inline, static]

Reads the DGCS register. Returns: The read value.

unsigned int readReg (  volatile unsigned int *    adr )  [inline, static]

Internal function to read a 32 PCI address, with eieio synch. Parameters: The  local address to read. Returns: The read value. Function to consolidate the method of reading of a 32bit PCI address. This form uses the EIEIO to ensure in order reads and writes.

int UNIV_bus_master_set (  void    )

Ensures the UNIVERSE II is a PCI bus master. Returns: The original value of the PCI CSR register. There is very little reason to use this routine. VxWorks initializes the UNIVERSE II to be a PCI bus master, so unless it has been 'unset' there is no reason to set it. It is provided only in the interest of completeness.

void UNIV_dcp_array_init (  struct _UNIV_dcp *    dcpp, int    cnt )

Initializes an array of Universe DMA Command packets to form a circular list. Only the link field is filled in. Parameters: dcpp  An array of command packets. cnt  The number of elements in the command packets. This routine is provided only as a convenience. It will probably be used as an example for the user to write his own initialization.

void UNIV_dcp_complete (  struct _UNIV_dcp *    dcpp, unsigned int    dctl, unsigned int    vmeAdr, unsigned char *    lclAdr, int    nbytes )

Complete the DMA Command Packet, ie finishes the job UNIV_dcp_array_init started. Parameters: dcpp  Pointer the the DMA Command Packet to complete. dctl  The DCTL control word. vmeAdr  The VME address lclAdr  The local address nbytes  The number of bytes to transfer. This completes the DMA command packet. The attributes of the transfer, ie, the direction, the datawidth, the VME address space, etc. are all controlled by the DCTL control word.

unsigned int UNIV_DCPP_read (  void    )

Reads the DCPP register, (Command Packet Pointer). Returns: The read value.

void UNIV_DCPP_write (  const struct _UNIV_dcp *    dcpp )

Write the DCPP register with the head of a DMA linked list. Parameters: dcpp  The DMA linked list head.

unsigned int UNIV_DGCS_bclr (  unsigned int    bitsToClr )

Clears the specified bits in the DGCS register, (General Control/Status Register). Parameters: bitsToClr  The value to write. Returns: The original value before modification. Clears the specified bits. This implements the following pseudocode *adr &= ~bitsToClr; Warning: This is not done in an indivisible manner.

unsigned int UNIV_DGCS_bmod (  unsigned int    modMsk, unsigned int    value )

Modifies a selected set of bits in the DGCS register. Parameters: modMsk  Which bits to modify. value  The new values. Returns: The original value before modification. Warning: This is not done in an indivisible manner.

unsigned int UNIV_DGCS_bset (  unsigned int    bitsToSet )

Sets the specified bits in the DGCS register. Parameters: bitsToSet  The set mask. Bits set to 1 are set. Returns: The original value before the bits are set. Sets the specified bits. This implements the following pseudocode *adr |= bitsToSet; Warning: This is not done in an indivisible manner.

unsigned int UNIV_DGCS_read (  void    )

Reads the DGCS register, (General Control/Status Register. Returns: The read value.

unsigned int UNIV_DGCS_write (  unsigned int    value )

Writes the DGCS register, (General Control/Status Register). Parameters: value  The value to write.

unsigned int UNIV_DTBC_read (  void    )

Reads the DTBC register, (Transfer Byte Count). Returns: The read value.

void UNIV_DTBC_write (  unsigned int    byteCount )

Writes the DTBC register, (Transfer Byte Count). Parameters: byteCount  The value of the transfer byte counter.

unsigned int UNIV_go (  void    )

Initiates a start on on a DMA operation by hitting to GO bit in the DGCS register. Returns: The original value of the DGCS register before the GO bit was set.

void UNIV_go_at (  struct _UNIV_dcp *    head )

This initiates a chain UNIV transfer by the Universe at the specified command head. Parameters: head  Pointer to the head of the linked list of command packets. This initiates a chain UNIV transfer by the Universe at the specified command head. It is assumed that the linked list has been programmed and is properly terminated. After the transfer count is cleared and the head of the command packet is placed in the Command Packet Pointer register, the GO bit is set. An EIEIO instruction should be performed right before the GO bit is set to ensure that the previous two writes have been flushed to the UNIV registers. It is recommended that this function, rather the combination be used, since this function avoids unnecessary EIEIO's.

int UNIV_int_connect (  unsigned int    which, UNIV_isr    routine, void *    parameter )

Connects a ISR routine to service the UNIVERSET II interrupts. Parameters: which  A bit mask of which interrupts to service. routine  The interrupt service routine. The callback signature is defined by the typedef UNIV_isr and is void (*isr_routine) (void *parameter) Parameters: parameter  A user supplied parameter passed transparently through to the ISR routine. Returns: Status. Except in very simple cases, any realistic implementation will connect to all possible sources. A layer of software will then have to be written to handle the dispatching of the interrupts to correct user. A possible model is a QIO model, where the user submits IO requests to a central 'driver'. The IOs are placed on a que and the driver services them one by one. Part of the IO information would be a user supplied callback routine to handle the asynchronous completion. The which parameter enable the sources on the Universe to generate interrupts. These are from the set UNIV_M_DGCS_INT_P_ERR UNIV_M_DGCS_INT_VERR UNIV_M_DGCS_INT_LERR UNIV_M_DGCS_INT_DONE UNIV_M_DGCS_INT_HALT UNIV_M_DGCS_INT_STOP These indicate which sources this particular ISR is willing to service.

int UNIV_int_disable (  void    )

Disables delivery of interrupts from the UNIVERSE II. Returns: Status

int UNIV_int_enable (  void    )

Enables delivery of interrupts from the UNIVERSE II. Returns: Status

unsigned int UNIV_request_halt (  void    )

Request a halt on an ongoing DMA operation. Returns: The original value of the DGCS register before the HALT_REQ bit was set. A HALT request is honored at the end of processing a DMA packet. The UNIVERSE II User's manual (p 2-90) states: "Linked-list operation can be halted by setting the HALT_REQ bit in the DGCS register. When the HALT_REG bit is set, the DMA terminates when all transfers defined by the current command packet is complete. It then load the next command packtet into its registers. The HALT bit in the DGCS register is asserted, and the ACT bit in the DGCS register is cleared. The PROCESSED bit in the linked-list is set to "1" approximately 1us after the HALT bit is set: therefore after a DMA halt the user should wait at least 1us before checking the PROCESSED bit." "The DMA can be restarted by clearing the HALT status bit and setting the GO bit if desired during the same register write. If the DMA is restarted, the ACT is set by the Universe II and execution continues as if no HALT had occurred: i.e. the Universe II processes the current command packet." Note that the HALT is done as an asynchronous operation, it is merely a request to HALT. The user must wait till the halt is actually done by either fielding the HALT interrupt or polling the HALTED status bit.

unsigned int UNIV_request_stop (  void    )

Request a stop on an ongoing DMA operation. Returns: The original value of the DGCS register before the STOP_REQ bit was set. A STOP request waits until all buffered data is written. The Universe II User's manual (page 2-90) states: "In contrast to a HALT, the DMA can also be immediately terminated through the STOP_REQ bit. This will stop all DMA operations on the source bus immediately, and set the STOP bit in the same register when the last piece of queued data in the DMA FIFO has been written to the destination bus." "Once stopped the DVA, DLA and DTBC registers contain values indicating the addresses to read/write and the number of bytes remaining in the transfer. Clearing the STOP bit and setting the GO bit will cause the DMA to start up agian from where it left off, including continuing with subsequent command packets in the list." Note that the STOP is done as an asynchronous operation, it is merely a request to STOP. The user must wait till the halt is actually done by either fielding the STOP interrupt or polling the HALTED status bit.

void writeDGCS (  unsigned int    value )  [inline, static]

Writes the DGCS register. Parameters: value  The value to write.

void writeReg (  volatile unsigned int *    adr, unsigned int    value )  [inline, static]

Internal function to write a 32 PCI address, with eieio synch. Parameters: adr  The local address to write. value  The value to write. Function to consolidate writing of a 32bit PCI address with a known value. This is done so that any common error checking code can be inserted here. This form uses the EIEIO to ensure in order reads and writes.

---