---

BFI.c File Reference

Balloon Flight Interrupt Handling, Implementation. More...

#include <semLib.h>
#include <intLib.h>
#include <errno.h>
#include <objLib.h>
#include <iv.h>
#include "BBC/BUG.h"
#include "BBC/INT.ih"
#include "BTU/TEM_ids.h"
#include "BTU/TEM_temInt.h"
#include "BFU/BFM.h"
#include "BFU/BFI.h"

Data Structures
struct	_BFI_gsc
	Group service context. More...
struct	_BFI_gscList
	Collection of all group service contexts. More...
struct	_BFI_ssc
	System Service Context. More...
Defines
#define	BFI_M_TEM_INT_ALLOC_MSK   (BFI_M_INT_SRC_TEMS << (32 - BFI_K_INT_SRC_TEMS))
	A left justified global interrupt mask is defined which contains a value representing interrupts from all the tems, arranged a nibble / TEM.
#define	BIT(_l32, _n)   ((_l32 >> _n) & 1)
	Returns the value of n th bit of 32 bit word _l.
#define	BITC(_l32, _n)   (((_l32 >> _n) & 1) ^ 1)
	Returns the value of the complement n th bit of 32 bit word _l.
#define	BITS(_l32, _r, _w)   ((_l32 >> _r) & _w)
	Returns the right justified value of bit field. More...
#define	BFI_S_ICW_TEMID   4
	Size of the TEM id field.
#define	BFI_S_ICW_IRPTS   4
	Size of the interrupt source mask field.
#define	BFI_S_ICW_GRPS   24
	Size of the service group mask field.
#define	BFI_V_ICW_TEMID   0
	Right shift needed to extract tem id.
#define	BFI_V_ICW_IRPTS   (BFI_V_ICW_TEMID + BFI_S_ICW_TEMID)
	Right shift needed to extract source mask.
#define	BFI_V_ICW_GRPS   (BFI_V_ICW_IRPTS + BFI_S_ICW_IRPTS)
	Right shift needed to extract group mask.
#define	BFI_N_ICW_TEMID   ((1<<BFI_S_ICW_TEMID)-1)
	Left justified mask to extract tem id.
#define	BFI_N_ICW_IRPTS   ((1<<BFI_S_ICW_IRPTS)-1)
	Left justified mask to extract source mask.
#define	BFI_N_ICW_GRPS   ((1<<BFI_S_ICW_GRPS )-1)
	Left justified mask to extract group mask.
#define	BFI_M_ICW_TEMID   (BFI_N_ICW_TEMID << BFI_V_ICW_TEMID)
	In place mask to extract tem id.
#define	BFI_M_ICW_IRPTS   (BFI_N_ICW_IRPTS << BFI_V_ICW_IRPTS)
	In place mask to extract source mask.
#define	BFI_M_ICW_GRPS   (BFI_N_ICW_GRPS << BFI_V_ICW_GRPS)
	In place mask to extract group mask.
#define	extractGrps(_icw)   ((_icw >> BFI_V_ICW_GRPS ) & BFI_N_ICW_GRPS)
	Macro to extract the group mask field.
#define	extractIrpts(_icw)   ((_icw >> BFI_V_ICW_IRPTS) & BFI_N_ICW_IRPTS)
	Macro to extract the source mask field.
#define	extractTemid(_icw)   ((_icw >> BFI_V_ICW_TEMID) & BFI_N_ICW_TEMID)
	Macro to extract the tem id field.
#define	insertGrps(_grps)   ((_grps & BFI_N_ICW_GRPS )<<BFI_V_ICW_GRPS )
	Macro to insert the group mask field.
#define	insertIrpts(_irpts)   ((_irpts & BFI_N_ICW_IRPTS)<<BFI_V_ICW_IRPTS)
	Macro to insert the source mask field.
#define	insertTemid(_temid)   ((_temid & BFI_N_ICW_TEMID)<<BFI_V_ICW_TEMID)
	Macro to insert the tem id field.
#define	BFI_K_INT_MAX   (BFI_K_INT_SRC_TEMS)
	Maximum number of interrupt sources. More...
Typedefs
typedef _BFI_gsc	BFI_gsc
	Typedef for struct _BFI_gsc. More...
typedef _BFI_gscList	BFI_gscList
	Typedef for struct _BFI_gscList. More...
typedef _BFI_ssc	BFI_ssc
	Typedef for struct _BFI_ssc. More...
typedef unsigned int	BFI_icw
	Interrrupt context word.
Functions
void	BFI_service (BFI_icw icw)
	The VME interrupt service routine. More...
int	FFS (unsigned int mask)
	Provides a straightforward interface to the CNTLZW machine instruction. More...
int	allocate (unsigned int *mask)
	Allocates the first available group service context block. More...
unsigned int	connect (const struct _TEM_tem *tems, enum _TEM_temId temId, const BFI_gsc *gsc, int groups)
	Connects all interrupts associated with the specified TEM. More...
int	BFI_connect (void)
	Connects all interrupts to their specified handlers. More...
unsigned int	BFI_evtThresholdsSet (unsigned int temList, const unsigned int *thresholds)
	Sets the event threshold for the specified set of TEMS. More...
int	BFI_groupAdd (unsigned int irpts)
	Defines a group to consist of the specified list of interrupts to service. More...
unsigned int	BFI_groupDisable (BFI_group grpId, unsigned int disable)
	Disables the specified list of interrupts for the specified group. More...
unsigned int	BFI_groupEnable (BFI_group gscId, unsigned int enable)
	Disables the specified list of interrupts for the specified group. More...
unsigned int	BFI_groupPend (BFI_group groupId, int timeout)
	Waits for the firing of any interrupt associated with the specified synchronization group. More...
int	BFI_groupSignal (BFI_group groupId, unsigned int irpts)
	Allows one to set a soft interrupt on the specified synchronization group. More...
unsigned int	BFI_init (const struct _BFM_dsc *bfm, unsigned int temList, const unsigned int *levels, const unsigned int *base)
	Initializes the system service context. Each active TEM has an interrupt level and a base vector assigned to it. More...
unsigned int	BFI_errorsGather (unsigned int irpts)
	Returns a 32 bit mask with the reason for the error interrupts decoded. More...
unsigned int	BFI_masterDisable (unsigned int temList)
	Disables the master interrupt enable for the specified list of TEMs. More...
unsigned int	BFI_masterEnable (unsigned int temList)
	Enables the master interrupt enable for the specified list of TEMs. More...
unsigned int	BFI_masterReset (unsigned int temList)
	Reset the master interrupt enable for the specified list of TEMs. This effectively clears all pending interrupts. More...
int	BFI_minEventsGet (unsigned int temList, unsigned int *nevts)
	Returns the minimum number of events pending from the specified list of tems, ie temList. More...
unsigned int	BFI_trim (unsigned int temList, unsigned int intList)
	Convenience routine to trim the interrupt sources associated with unused TEMs from the list. More...
unsigned int	BFI_vmeDisable (unsigned int temList)
	Disables the VME interrupt for the specified list of TEMs. More...
unsigned int	BFI_vmeEnable (unsigned int temList)
	Enables the VME interrupt for the specified list of TEMs. More...
Variables
BFI_ssc	Bfi_Ssc
	Global to an instance of this system servicing context block.

---

Detailed Description

Balloon Flight Interrupt Handling, Implementation.

Author:

JJRussell - russell@slac.stanford.edu

---

Define Documentation

#define BFI_K_INT_MAX   (BFI_K_INT_SRC_TEMS)

Maximum number of interrupt sources. Since an interrrupt can be associated with only one group, this number determines the maximum number of possible groups. Because a group may service more than one interrupt, the number of groups actually used may be smaller than this number, even in a system with all interrupts active.

#define BITS (  _l32, _r, _w    )     ((_l32 >> _r) & _w)

Returns the right justified value of bit field. Parameters: _l  The 32 bit word to extract the bit field from. _r  The bit number of least significant bit of the bit field. _w  The width of the bit field.

---

Typedef Documentation

BFI_gsc

Typedef for struct _BFI_gsc. Contains all the information needed to define and control an interrupt group. An interrupt group can be associated with multiple interrupt sources, but it always delivers its response to one listener. This allows multiple interrupts to be handle within a single context. For example, all L1T interrupts from each TEM could be enabled and associated with a single group. If any L1T interrupt becomes active, then the context responsible for handling this group will be notified with a wake up call and a parameter indicating which sources are active.

BFI_gscList

Typedef for struct _BFI_gscList. The current implementation supports 24 distinct groups. This data structure services as a pool for BFI_gsc context blocks needed to define a group service context. Blocks are allocated for this pool. The free field is a list of the free, unallocated, group service context blocks, expressed as a bit mask. It is initialized to have its most significant 24 bits set, indicating that all blocks are free. (The left justification is because the allocator uses a CNLZ, count leading zeros instruction to find the first free block.

BFI_ssc

Typedef for struct _BFI_ssc. Gathers together all the information needed to define and control the interrupts.

---

Function Documentation

int allocate (  unsigned int *    mask )  [inline, static]

Allocates the first available group service context block. Parameters: mask  The free list, expressed as a left justified bit mask. Returns: An index between 0 - 23 if the allocation is successful. Returns -1 if the allocation fails. This allocator is multithread safe. If the allocation is successful, the allocated block is marked as no longer free.

int BFI_connect (  void    )

Connects all interrupts to their specified handlers. Returns: A list of TEMs that failed to properly connect Connects all interrupts to their specified handlers. The context parameter is the Interrupt Control Word. This word contains the following 3 pieces of information 1. The ID of the TEM to service. 2. The bit mask of interrupts that need servicing 3. The bit mask of group ids that perform the servicing. All active interrupts must have one and only one group associated with them. NOTE ---- Due to the way VxWorks handles interrupt connects, it makes sense to connect to an interrupt once and only once. This, in turn, leads to the situation where all must be connected at the same time.

unsigned int BFI_errorsGather (  unsigned int    irpts )

Returns a 32 bit mask with the reason for the error interrupts decoded. Parameters: irpts  The active interrupts. Each active TEM error interrupt bit is examined for the source of the error. These reasons are combined into a 32 summary error reason word. The mapping of this word is defined by the enumeration BFI_V_INT_ERR_SRC_TEM and BFI_M_INT_ERR_SRC_TEM. Warning: It is assumed that irpts will contain interrupts only active TEMs/ Warning: This routine is somewhat kludged together. It does not use the usual BTUD database to locate the error bits. If those bits move about, then this routine needs to be modified and recompiled.

unsigned int BFI_evtThresholdsSet (  unsigned int    temList, const unsigned int *    thresholds )

Sets the event threshold for the specified set of TEMS. Parameters: temList  The list of TEMs, expressed as a bit mask, to set thresholds for. thresholds  An array of thresholds, indexed by TEM ID. Returns: The list of TEMs requested but not set. While in practice it makes no sense to set the thresholds on the various TEMs to different values, this routine does allow it. Being a low level routine it does not force a certain policy. Bizarre as it may seem, one could imagine a test case which would like to do this.

int BFI_groupAdd (  unsigned int    irpts )

Defines a group to consist of the specified list of interrupts to service. Parameters: irpts  The list of interrupts, expressed as a bit mask, to service. Returns: A handle used to access the group

unsigned int BFI_groupDisable (  BFI_group    group, unsigned int    disable )

Disables the specified list of interrupts for the specified group. Parameters: group  The group to disable the interrupts for. disable  The list of interrupts, expressed as a bit mask, to disable. Returns: The list of serviceable interrupts which could not be disabled

unsigned int BFI_groupEnable (  BFI_group    group, unsigned int    enable )

Disables the specified list of interrupts for the specified group. Parameters: group  The group to disable the interrupts for. enable  The list of interrupts, expressed as a bit mask, to disable. Returns: The list of serviceable interrupts which could not be enabled

unsigned int BFI_groupPend (  BFI_group    group, int    timeout )

Waits for the firing of any interrupt associated with the specified synchronization group. Parameters: group  The group to pend on. timeout  A timeout. If specified as >0, then a timeout interrupt will be delivered upon expiration. If specified as -1, the timeout is infinite. Returns: A bit mask of interrupts that need to be serviced

int BFI_groupSignal (  BFI_group    group, unsigned int    irpts )

Allows one to set a soft interrupt on the specified synchronization group. Parameters: group  The group to set the soft interrupt on. Returns: Status This mechanism allows the software to deliver a signal to a group. These signals act just about the same way as an interrupt, but whereas interrupts are global, soft interrupts are private to a group. That means the same soft interrupt number can be reused across multiple groups. The signalling is confined to within that group. One could have implemented a different scheme where a software interrupt was associated with one and only one group, but there seemed to be no real advantage and it was more complicated. The only advantage I could think of was if the same soft interrupt was associated with multiple groups, allowing a kind of broadcast wake-up capability. This was an interesting idea, but did not mirror the usage of hard interrupts being constrained to be connected with only one group. Currently the only failure mode is if the semGive fails. If one specifies interrupts other than soft interrupts, they are quietly pitched on the ground, that is only the soft interrupts in the irpts will be signalled, any other bits are ignored.

unsigned int BFI_init (  const struct _BFM_dsc *    bfm, unsigned int    temList, const unsigned int *    levels, const unsigned int *    base )

Initializes the system service context. Each active TEM has an interrupt level and a base vector assigned to it. Parameters: bfm  Handle to the Balloon Flight Tems description temList  List of tems to make the assign for. If specified as -1, then all actives TEMs will be assigned. levels  An array, indexed by TEM number, giving the VME interrupt level to assign to each TEM. The level must be a number in the range 0-7. base  An array, indexed by TEM number, giving the base vector to assign to each TEM. The base vector must be a number selected from the set of 0x60, 0x80, 0xA0, 0xC0 Returns: List of TEMs successfully initialized

unsigned int BFI_masterDisable (  unsigned int    temList )

Disables the master interrupt enable for the specified list of TEMs. Parameters: temList  The list of target TEMs Returns: The list of TEMs for which the operation failed.

unsigned int BFI_masterEnable (  unsigned int    temList )

Enables the master interrupt enable for the specified list of TEMs. Parameters: temList  The list of target TEMs Returns: The list of TEMs for which the operation failed.

unsigned int BFI_masterReset (  unsigned int    temList )

Reset the master interrupt enable for the specified list of TEMs. This effectively clears all pending interrupts. Parameters: temList  The list of target TEMs Returns: The list of TEMs for which the operation failed. Since a master reset clears all pending interrupts, this service will likely be used at initialization time or when the system is in an error condition.

int BFI_minEventsGet (  unsigned int    temList, unsigned int *    nevts )

Returns the minimum number of events pending from the specified list of tems, ie temList. Parameters: temList  The list of TEMS to search. A -1 searches all the active TEMS. nevts  Filled in with the number of events in each TEM. This may be specified as NULL. Returns: The minimum number or pending events. Finds the minimum number of events pending amongst the specified list of TEMs. This number is the maximum number of events that can be safely read. The search is always limited to the list of active TEMs.

void BFI_service (  BFI_icw    icw )

The VME interrupt service routine. Parameters: icw  The interrupt context word. Since this routine is connected to multiple interrupts, this parameter is used to distinguish which interrupt(s) is/are being serviced. Service the specified interrupts. The list of groups serviced by this interrupt are woke up. This routine is called back when a particular set of interrupts occurs for a particular VME interrupt level. Because the TEM delivers all its interrupts at the same VME interrupt level, the association of interrupt level with a specific TEM can be made. This routine is meant to service all interrupts possibilities that a single TEM may produce. When multiple interrupts are present, it may be that more than one group needs to be tickled (ie have its semaphore given). Warning: This is not a user callable routine. PROGRAMMING NOTE ---------------- Perhaps a good optimization would be to isolate the set of interrupt vectors that service one and only one group to a specific routine. That would save the looping structure and the code that goes with it.

unsigned int BFI_trim (  unsigned int    temList, unsigned int    intList )

Convenience routine to trim the interrupt sources associated with unused TEMs from the list. Parameters: temList  The list of TEMs whose interrupts should be preserved. intList  The list of interrupts to trim. Returns: The trimmed list of interrupts. This represents the set of active interrupts in the system.

unsigned int BFI_vmeDisable (  unsigned int    temList )

Disables the VME interrupt for the specified list of TEMs. Parameters: temList  The list of target TEMs Returns: The list of TEMs for which the operation failed. Disables the VME interrupt for the specified list of TEMs. Technically what is disabled is an VME interrupt level, but, there is a one to one correspondence of a VME interrupt level with a TEM.

unsigned int BFI_vmeEnable (  unsigned int    temList )

Enables the VME interrupt for the specified list of TEMs. Parameters: temList  The list of target TEMs Returns: The list of TEMs for which the operation failed. Ensables the VME interrupt for the specified list of TEMs. Technically what is enabled is an VME interrupt level, but, there is a one to one correspondence of a VME interrupt level with a TEM.

unsigned int connect (  const struct _TEM_tem *    tems, enum _TEM_temId    temId, const BFI_gsc *    gsc, int    groups )  [static]

Connects all interrupts associated with the specified TEM. Parameters: tems  The TEM database. temId  The id of the TEM to connect, ie ACD, TKR, CAL gsc  The array of group service context blocks. groups  The list of groups to connect. Returns: 0 if succesfully, else a list of interrupts that failed to connect.

int FFS (  unsigned int    mask )  [inline, static]

Provides a straightforward interface to the CNTLZW machine instruction. Parameters: mask  The word to find the first set bit in Returns: 0-32 indicating the first set bit. Returning 32 indicates that there are no bits set. This is an internal utility routine used by the group service context block allocator.

---