---

GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > TPG / V3-1-1

Constituent: gtb     Tag: mv2304

---

         

---

GTB.c File Reference

Implements input/output methods. More...

#include "GNAT/VME.h"
#include "TPG/GTBtypes.h"
#include "TPG/GTB.h"
#include "GTB_p.h"

Include dependency graph for GTB.c:

Defines
#define	PACKET_READY_INTR_LEVEL   (3)
	Packet ready interrupt level.
#define	PACKET_READY_INTR_VECTOR   (200)
	Packet ready interrupt vector.
#define	GTB_DEBUG_OFF   0x00000000
	GTB debug off.
#define	GTB_DEBUG_CLKS   0x00000010
	GTB debug clocks.
#define	FIFO_TEST_LENGTH   8
	FIFO test length.
Functions
int	boardProbe (unsigned int)
	attempts to detect the presence of the board at the localAdr location
int	gtbIsFullFifo (gtbHndl h, int fifoId)
	Test for FIFO full (what).
int	gtbIsEmptyFifo (gtbHndl h, int fifoId)
	Test for FIFO empty (what).
int	gtbFifoTest (gtbHndl h, int fifoId)
	Test FIFO (what).
gtbHndl	gtbOpen (unsigned int physAddr)
	maps the physical address to an instance of the driver object
int	gtbClose (gtbHndl h)
	shuts down the device attached to handle
int	gtbGetLogicalAddr (gtbHndl h, unsigned int *addr)
	returns the logical address attached to handle
int	gtbGetPhysAddr (gtbHndl h, unsigned int *addr)
	returns the physical address attached to handle
int	gtbProbe (gtbHndl h)
int	gtbFlushAllF (gtbHndl h)
	flushes the record and playback FIFOs of the board referenced by handle.
int	gtbFlushF (gtbHndl h, int fifoId)
	flushes the playback FIFO of the board referenced by handle.
int	gtbFlushRF (gtbHndl h)
	flushes the record FIFO of the board referenced by handle.
int	gtbFlushPF (gtbHndl h)
	flushes the playback FIFO of the board referenced by handle.
int	gtbReset (gtbHndl h)
	resets the board referenced by handle. Returns the board to a known state.
int	gtbHWver (gtbHndl h, unsigned short int *version, unsigned short int *revision)
	fetches the hardware version and revision numbers from the board
int	gtbSWver (gtbHndl h, unsigned short int *version, unsigned short int *revision)
	fetches the software version and revision numbers from the board
int	gtbWriteF16 (gtbHndl h, unsigned short int val, int fifoId)
	writes the 16-bit short word val to the play back FIFO
int	gtbWriteF16n (gtbHndl h, unsigned short int nItem, unsigned short int val, int fifoId)
	writes the 16-bit short word val to the play back FIFO nItem times
int	gtbWriteF16v (gtbHndl h, unsigned short int nVal, unsigned short int *aVal, int fifoId)
	writes the array of 16-bit short words aVal to the play back FIFO
int	gtbWriteF32 (gtbHndl h, unsigned int val, int fifoId)
	writes the 32-bit word val to the play back FIFO
int	gtbWriteF32n (gtbHndl h, unsigned short int nItem, unsigned int val, int fifoId)
	writes the 32-bit word val to the play back FIFO
int	gtbWriteF32v (gtbHndl h, unsigned int nVal, unsigned int *aVal, int fifoId)
	writes the array of 32-bit words aVal to the play back FIFO
int	gEnableClk0 (gtbHndl h)
	Enables continuous clock on channel 0, generated by board.
int	gtbEnableAllF (gtbHndl h)
	Prepares both the playback and record FIFOs for writing, by taking them out of reset.
int	gtbEnableF (gtbHndl h, int fifoId)
	Prepares the play back FIFO for writing, by taking it out of reset.
int	gtbEnablePF (gtbHndl h)
	Prepares the play back FIFO for writing, by taking it out of reset.
int	gtbEnableRF (gtbHndl h)
	Prepares the record FIFO for writing, by taking it out of reset.
int	gtbClrALLhist (gtbHndl h)
	Clears the latched occupancy status for both Playback and Record FIFOs.
int	gtbClrFhist (gtbHndl h, int fifoId)
	Clears the latched occupancy status for the Playback FIFOs.
int	gtbClrPFhist (gtbHndl h)
	Clears the latched occupancy status for the Playback FIFOs.
int	gtbClrRFhist (gtbHndl h)
	Clears the latched occupancy status for the record FIFO.
int	gtbStartPB (gtbHndl h)
	Start the playblack sequence.
int	gtbSetAcqSrc (gtbHndl h, unsigned int src)
	Set the source for initiating playback.
int	gtbSetRecDly (gtbHndl h, unsigned char dly)
	Set the delay for the read back FIFO.
int	gtbSetClkDly (gtbHndl h, unsigned char dly)
	Set the delay for the channel 0 clock.
int	gtbSetIrqLevel (gtbHndl h, unsigned int level)
	Set interrupt level for this gnatHandle.
int	gtbGetIrqLevel (gtbHndl h, unsigned int *level)
	Get interrupt level for this gnatHandle.
int	gtbSetIrqVector (gtbHndl h, unsigned int vector)
	Set interrupt vector for this gnatHandle.
int	gtbGetIrqVector (gtbHndl h, unsigned int *vec)
	Get interrupt vector for this gnatHandle.
int	gtbSetIrqDelay (gtbHndl h, unsigned int dly)
	Set interrupt delay for this gnatHandle.
void	srvIntr (gtbHndl h)
	ISR that gives the m_syncSem semaphore when the record FIFO has a packet ready.
int	gtbConnectIrq (gtbHndl h)
	Prepares driver and board for interrupts.
int	gtbEnableIrq (gtbHndl h)
	Enables interrupt.
int	gtbDisableIrq (gtbHndl h)
	Disables interrupt.
int	gtbSetActive (gtbHndl h, unsigned int mode)
	Set active member for gnatHandle.
int	gtbGetActive (gtbHndl h, unsigned int *mode)
	Returns current active mode for gnatHandle.
int	gtbFlushPipe (gtbHndl h)
	Purges stale cruft from internal FPGA state machine.
int	gtbSetOutMask (gtbHndl h, unsigned int mask)
	Sets the output XOR bit mask used when writing to the FIFO.
int	gtbGetOutMask (gtbHndl h, unsigned int *mask)
	Gets the output XOR bit mask used when writing to the FIFO.
int	gtbTakeIntSem (gtbHndl h)
	Takes the interrupt sync semaphore.
int	gtbVersion (gtbHndl h, unsigned short hwVer, unsigned short hwRev, unsigned short swVer, unsigned short swRev)
	Checks the COMM Board hardware version/revision.
int	gtbReady (gtbHndl h, int timeOut)
	Waits for the COMM board to become ready, via polling.
int	gtbLockFIFO (gtbHndl h, int timeOut)
	Locks access to the COMM board FIFO.
int	gtbUnLockFIFO (gtbHndl h)
	Unlocks access to the COMM board FIFO.
gtbType_t	gtbType (gtbHndl h)
	Return gtb type.
gtbClk_t	gtbClkDetect (gtbHndl h)
	Return (what).
void	gtbClkForce (gtbHndl h, gtbClk_t clk)
	Force clock (what).
void	gtbClkUse (gtbHndl h, gtbClk_t clk)
	Use clock (what).
void	gtbVetoSelect (gtbHndl h)
	Select veto (what).
void	gtbCnoSelect (gtbHndl h)
	Select CNO (what).
void	gtbArm (gtbHndl h, gtbTrig_t trig)
	Arm trigger (what).
void	gtbDisarm (gtbHndl h, gtbTrig_t trig)
	Disarm trigger (what).
int	gtbIsValidHandle (gtbHndl h)
	Is handle valid.
Variables
unsigned int	gtbDebug = GTB_DEBUG_OFF
	Set debugging on/off.

---

Detailed Description

Implements input/output methods.

Author:

Mark McDougald -- mark@slac.stanford.edu

---

Function Documentation

int boardProbe (  unsigned int  localAddr  )  [static]

attempts to detect the presence of the board at the localAdr location Parameters: localAddr  address of COMM I/O board Returns: 0 on success, non-zero for failure

int gEnableClk0 (  gtbHndl  h  )

Enables continuous clock on channel 0, generated by board. Parameters: h  handle of device Returns: GTB_OK on success

void gtbArm (  gtbHndl  h, gtbTrig_t  trig )

Arm trigger (what). Parameters: h  gnat driver handle previously allocated trig  Trigger to arm (what)

gtbClk_t gtbClkDetect (  gtbHndl  h  )

Return (what). Parameters: h  gnat driver handle previously allocated

void gtbClkForce (  gtbHndl  h, gtbClk_t  clk )

Force clock (what). Parameters: h  gnat driver handle previously allocated clk  clock (what)

Here is the call graph for this function:

void gtbClkUse (  gtbHndl  h, gtbClk_t  clk )

Use clock (what). Parameters: h  gnat driver handle previously allocated clk  clock (what)

int gtbClose (  gtbHndl  h  )

shuts down the device attached to handle Parameters: h  handle of device to close Returns: GTB_OK if close successful See also: gOpen()

int gtbClrALLhist (  gtbHndl  h  )

Clears the latched occupancy status for both Playback and Record FIFOs. Parameters: h  handle of device Returns: GTB_OK on success See also: gClrPFhist(), gClrRFhist() Clears the occupancy status flags ( Empty, Full, Almost Empty, Almost Full ) for both the record FIFO and the playback FIFO.

Here is the call graph for this function:

int gtbClrFhist (  gtbHndl  h, int  fifoId )

Clears the latched occupancy status for the Playback FIFOs. Parameters: h  handle of device fifoId  Id of FIFO to flush Returns: GTB_OK on success See also: gClrRFhist(), gClrALLhist() Clears the occupancy status flags ( Empty, Full, Almost Empty, Almost Full ) for the playback FIFO.

int gtbClrPFhist (  gtbHndl  h  )

Clears the latched occupancy status for the Playback FIFOs. Parameters: h  handle of device Returns: GTB_OK on success See also: gClrRFhist(), gClrALLhist() Clears the occupancy status flags ( Empty, Full, Almost Empty, Almost Full ) for the playback FIFO.

int gtbClrRFhist (  gtbHndl  h  )

Clears the latched occupancy status for the record FIFO. Parameters: h  handle of device Returns: GTB_OK on success See also: gClrPFhist(), gClrALLhist() Clears the occupancy status flags ( Empty, Full, Almost Empty, Almost Full ) for the record FIFO.

void gtbCnoSelect (  gtbHndl  h  )

Select CNO (what). Parameters: h  gnat driver handle previously allocated

int gtbConnectIrq (  gtbHndl  h  )

Prepares driver and board for interrupts. Parameters: h  handle of device Returns: GTB_OK on success

Here is the call graph for this function:

int gtbDisableIrq (  gtbHndl  h  )

Disables interrupt. Parameters: h  handle of device Returns: GTB_OK on success

void gtbDisarm (  gtbHndl  h, gtbTrig_t  trig )

Disarm trigger (what). Parameters: h  gnat driver handle previously allocated trig  Trigger to disarm (what)

int gtbEnableAllF (  gtbHndl  h  )

Prepares both the playback and record FIFOs for writing, by taking them out of reset. Parameters: h  handle of device Returns: GTB_OK on success See also: gEnableRF(), gEnablePF(), gWritePF32(), gWritePF32v(), gWritePF16(), gWritePF16v()

Here is the call graph for this function:

int gtbEnableF (  gtbHndl  h, int  fifoId )

Prepares the play back FIFO for writing, by taking it out of reset. Parameters: h  handle of device fifoId  FIFO Id Returns: GTB_OK on success See also: gEnableRF(), gEnableAllF(), gWritePF32(), gWritePF32v(), gWritePF16(), gWritePF16v()

int gtbEnableIrq (  gtbHndl  h  )

Enables interrupt. Parameters: h  handle of device Returns: GTB_OK on success

int gtbEnablePF (  gtbHndl  h  )

Prepares the play back FIFO for writing, by taking it out of reset. Parameters: h  handle of device Returns: GTB_OK on success See also: gEnableRF(), gEnableAllF(), gWritePF32(), gWritePF32v(), gWritePF16(), gWritePF16v()

int gtbEnableRF (  gtbHndl  h  )

Prepares the record FIFO for writing, by taking it out of reset. Parameters: h  handle of device Returns: GTB_OK on success See also: gEnablePF(), gEnableAllF(), gReadRF32(), gReadRF32v(), gReadRF16(), gReadRF16v()

int gtbFifoTest (  gtbHndl  h, int  fifoId )

Test FIFO (what). Parameters: h  handle of device to close fifoId  Id of FIFO to flush Returns: What

Here is the call graph for this function:

int gtbFlushAllF (  gtbHndl  h  )

flushes the record and playback FIFOs of the board referenced by handle. Parameters: h  handle of device Returns: GTB_OK if successful See also: gFlushRF(), gFlushPF()

Here is the call graph for this function:

int gtbFlushF (  gtbHndl  h, int  fifoId )

flushes the playback FIFO of the board referenced by handle. Parameters: h  handle of device fifoId  Id of FIFO to flush Returns: GTB_OK if successful

int gtbFlushPF (  gtbHndl  h  )

flushes the playback FIFO of the board referenced by handle. Parameters: h  handle of device Returns: GTB_OK if successful

int gtbFlushPipe (  gtbHndl  h  )

Purges stale cruft from internal FPGA state machine. Parameters: h  handle of device Returns: GTB_OK on success Purges stale data from internal FPGA pipeline by playing back one word of 0x3FFFF through the system.

Here is the call graph for this function:

int gtbFlushRF (  gtbHndl  h  )

flushes the record FIFO of the board referenced by handle. Parameters: h  handle of device Returns: GTB_OK if successful

int gtbGetActive (  gtbHndl  h, unsigned int *  mode )

Returns current active mode for gnatHandle. Parameters: h  handle of device mode  pointer to storage to hold current mode See also: gSetActive() Returns: GTB_OK on success Returns the current active mode for the gnatHandle. A value of 0 means inactive, while a non-zero value means active.

int gtbGetIrqLevel (  gtbHndl  h, unsigned int *  level )

Get interrupt level for this gnatHandle. Parameters: h  handle of device level  pointer to storage for interrupt level See also: gSetIrqVector, gSetIrqLevel, gGetIrqVector Returns: GTB_OK on success

int gtbGetIrqVector (  gtbHndl  h, unsigned int *  vec )

Get interrupt vector for this gnatHandle. Parameters: h  handle of device vec  interrupt vector to get See also: gSetIrqVector, gSetIrqLevel, gGetIrqLevel Returns: GTB_OK on success

int gtbGetLogicalAddr (  gtbHndl  h, unsigned int *  addr )

returns the logical address attached to handle Parameters: h  handle of device to close addr  pointer to storage for holding logical address Returns: GTB_OK on successs See also: gOpen()

int gtbGetOutMask (  gtbHndl  h, unsigned int *  mask )

Gets the output XOR bit mask used when writing to the FIFO. Parameters: h  handle of device mask  pointer to storage for XOR bit mask Returns: GTB_OK on success See also: gWritePF16(), gWritePF16v(), gWritePF32(), gWritePF32v(), gSetOutMask() Gets the XOR bit mask used when writing data to the playback FIFO.

int gtbGetPhysAddr (  gtbHndl  h, unsigned int *  addr )

returns the physical address attached to handle Parameters: h  handle of device to close addr  pointer to storage for holding physical address Returns: GTB_OK on successs See also: gOpen()

int gtbHWver (  gtbHndl  h, unsigned short int *  version, unsigned short int *  revision )

fetches the hardware version and revision numbers from the board Parameters: h  handle of device version  3 LSB contain hardware version number revision  3 LSB contain hardware revision number Returns: GTB_OK on success See also: gSWver()

int gtbIsEmptyFifo (  gtbHndl  h, int  fifoId )

Test for FIFO empty (what). Parameters: h  handle of device to close fifoId  Id of FIFO to flush Returns: What

int gtbIsFullFifo (  gtbHndl  h, int  fifoId )

Test for FIFO full (what). Parameters: h  handle of device to close fifoId  Id of FIFO to flush Returns: What

int gtbIsValidHandle (  gtbHndl  h  )

Is handle valid. Parameters: h  gnat driver handle previously allocated

int gtbLockFIFO (  gtbHndl  h, int  timeOut )

Locks access to the COMM board FIFO. Parameters: h  gnat driver handle previously allocated timeOut  timeout value in sysclk ticks Returns: GTB_OK on success or GTB_ERR_READY_TIMEOUT on timeout.

gtbHndl gtbOpen (  unsigned int  physAddr  )

maps the physical address to an instance of the driver object Parameters: physAddr  the physical address of the comm IO board Returns: OK for success See also: gClose() Attempts to map physAddr into a local (logical) address. If successful it binds the physical and logical address to the driver object refered to by handle. If unsuccessful it clears both the physical and local address for handle and returns ERROR.

Here is the call graph for this function:

int gtbProbe (  gtbHndl  h  )

Parameters: h  handle of device to probe Returns: GTB_OK if board probed. See also:

Here is the call graph for this function:

int gtbReady (  gtbHndl  h, int  timeOut )

Waits for the COMM board to become ready, via polling. Parameters: h  gtb driver handle previously allocated timeOut  timeout value in sysclk ticks Returns: GTB_OK on success or GTB_ERR_READY_TIMEOUT on timeout.

int gtbReset (  gtbHndl  h  )

resets the board referenced by handle. Returns the board to a known state. Parameters: h  handle of device to resest Returns: GTB_OK if board reset

int gtbSetAcqSrc (  gtbHndl  h, unsigned int  src )

Set the source for initiating playback. Parameters: h  handle of device src  source bit Returns: GTB_OK on success The src parameter defines which of two possible sources to use for initiating playback from the FIFOs. If is zero the source is the transition of bit 31 of the control register from 0 to 1. If is non-zero the source is the external signal brought in through the front panel LEMO connector labeled "START IN".

int gtbSetActive (  gtbHndl  h, unsigned int  mode )

Set active member for gnatHandle. Parameters: h  handle of device mode  mode to set handle to See also: gGetActive() Returns: GTB_OK on success Used to mode switch between commanding and event taking for single COMM board operation. A value of 0 means inactive, while a non-zero value means active.

int gtbSetClkDly (  gtbHndl  h, unsigned char  dly )

Set the delay for the channel 0 clock. Parameters: h  handle of device dly  the number of 2ns ticks to delay the channel 0 clock See also: gStartPB() Returns: GTB_OK on success Fix-up for timing skews between multiple COMM boards. The delay field is 6 bits wide, allowing for delays from 0 to 64ns in 2ns increments.

int gtbSetIrqDelay (  gtbHndl  h, unsigned int  dly )

Set interrupt delay for this gnatHandle. Parameters: h  handle of device dly  interrupt dly to set See also: gSetIrqLevel(), gSetIrqVector() Returns: GTB_OK on success

int gtbSetIrqLevel (  gtbHndl  h, unsigned int  level )

Set interrupt level for this gnatHandle. Parameters: h  handle of device level  interrupt level to set See also: gSetIrqVector, gSetIrqDelay, gGetIrqLevel, gGetIrqVector Returns: GTB_OK on success

int gtbSetIrqVector (  gtbHndl  h, unsigned int  vector )

Set interrupt vector for this gnatHandle. Parameters: h  handle of device vector  interrupt vector to set See also: gSetIrqLevel, gSetIrqDelay Returns: GTB_OK on success

int gtbSetOutMask (  gtbHndl  h, unsigned int  mask )

Sets the output XOR bit mask used when writing to the FIFO. Parameters: h  handle of device mask  XOR bit mask Returns: GTB_OK on success See also: gWritePF16(), gWritePF16v(), gWritePF32(), gWritePF32v(), gGetOutMask() Sets the XOR bit mask used when writing data to the playback FIFO.

int gtbSetRecDly (  gtbHndl  h, unsigned char  dly )

Set the delay for the read back FIFO. Parameters: h  handle of device dly  the number of 25ns ticks to delay the read back FIFO. See also: gStartPB() Returns: GTB_OK on success After starting playback wait dly 25ns intervals before clocking data into the record FIFO. The delay register is 8 bits wide, allowing for delays from 0 to 6.4usec in 25ns increments.

int gtbStartPB (  gtbHndl  h  )

Start the playblack sequence. Parameters: h  handle of device Returns: GTB_OK on success

int gtbSWver (  gtbHndl  h, unsigned short int *  version, unsigned short int *  revision )

fetches the software version and revision numbers from the board Parameters: h  handle of device version  3 LSB contain software version number revision  3 LSB contain software revision number Returns: GTB_OK on success See also: gHWver()

int gtbTakeIntSem (  gtbHndl  h  )

Takes the interrupt sync semaphore. Parameters: h  handle of device Returns: GTB_OK on success

gtbType_t gtbType (  gtbHndl  h  )

Return gtb type. Parameters: h  gnat driver handle previously allocated

int gtbUnLockFIFO (  gtbHndl  h  )

Unlocks access to the COMM board FIFO. Parameters: h  gnat driver handle previously allocated Returns: GTB_OK on success or GTB_ERR_READY_TIMEOUT on timeout.

int gtbVersion (  gtbHndl  h, unsigned short  hwVer, unsigned short  hwRev, unsigned short  swVer, unsigned short  swRev )

Checks the COMM Board hardware version/revision. Parameters: h  handle of device hwVer  COMM Board hardware version hwRev  COMM Board hardware revision swVer  COMM Board firmware version swRev  COMM Board firmware revision Returns: GTB_OK on success

Here is the call graph for this function:

void gtbVetoSelect (  gtbHndl  h  )

Select veto (what). Parameters: h  gnat driver handle previously allocated

int gtbWriteF16 (  gtbHndl  h, unsigned short int  val, int  fifoId )

writes the 16-bit short word val to the play back FIFO Parameters: h  handle of device val  16-bit short word to write to play back FIFO fifoId  FIFO Id Returns: GTB_OK on success See also: gWritePF16v(), gWritePF32(), gWritePF32v(), gSetOutMask() The data is written to the play back FIFO -- the data is first XOR-ed with h->outMask before writing to the FIFO.

int gtbWriteF16n (  gtbHndl  h, unsigned short int  nItem, unsigned short int  val, int  fifoId )

writes the 16-bit short word val to the play back FIFO nItem times Parameters: h  handle of device nItem  number of times to writes val to FIFO val  16-bit short word to write to play back FIFO fifoId  FIFO Id Returns: GTB_OK on success See also: gWritePF16v(), gWritePF32(), gWritePF32v(), gSetOutMask() nItem copies of val is written to the play back FIFO -- the data is first XOR-ed with h->outMask before writing to the FIFO.

int gtbWriteF16v (  gtbHndl  h, unsigned short int  nVal, unsigned short int *  aVal, int  fifoId )

writes the array of 16-bit short words aVal to the play back FIFO Parameters: h  handle of device nVal  number of elements in aVal aVal  pointer to array of 16-bit short words fifoId  FIFO Id Returns: GTB_OK on success See also: gWritePF16(), gWritePF32(), gWritePF32v(), gSetOutMask() The data is written to the play back FIFO -- the data is first XOR-ed with h->outMask before writing to the FIFO.

int gtbWriteF32 (  gtbHndl  h, unsigned int  val, int  fifoId )

writes the 32-bit word val to the play back FIFO Parameters: h  handle of device val  32-bit word to write to play back FIFO fifoId  FIFO Id Returns: GTB_OK on success See also: gWritePF32v(), gWritePF16(), gWritePF16v(), gSetOutMask() The data is written to the play back FIFO -- the data is first XOR-ed with h->outMask before writing to the FIFO.

int gtbWriteF32n (  gtbHndl  h, unsigned short int  nItem, unsigned int  val, int  fifoId )

writes the 32-bit word val to the play back FIFO Parameters: h  handle of device nItem  number of times to writes val to FIFO val  32-bit word to write to play back FIFO fifoId  FIFO Id Returns: GTB_OK on success See also: gWritePF32v(), gWritePF16(), gWritePF16v(), gSetOutMask() nItem copies of val is written to the play back FIFO -- the data is first XOR-ed with h->outMask before writing to the FIFO.

int gtbWriteF32v (  gtbHndl  h, unsigned int  nVal, unsigned int *  aVal, int  fifoId )

writes the array of 32-bit words aVal to the play back FIFO Parameters: h  handle of device nVal  number of elements in aVal aVal  pointer to array of 32-bit words fifoId  FIFO Id Returns: GTB_OK on success See also: gWritePF32(), gWritePF16(), gWritePF16v(), gSetOutMask() The data is written to the play back FIFO -- the data is first XOR-ed with h->outMask before writing to the FIFO.

void srvIntr (  gtbHndl  h  )

ISR that gives the m_syncSem semaphore when the record FIFO has a packet ready. Parameters: h  gnat driver handle previously allocated Returns: void

---