Data masks, Pack and FindChannelLimits

Top  Previous  Next

The user is free to assign any channel(s) he wants to a signal.  They do not have to be consecutive.  In fact multi-bit signals (like buses) do not even have to be contiguous.  For example, a 4 bit bus could be assigned to channels 3,9,21 and 32.  The only rule is that the bits are ordered by their channel numbers.  The lowest channel number assigned is the LSB of the bus.  One signal's channels can be interspersed with other signal's channels.  Mini plug-ins do not have to worry about this as the pre-processor normalizes the data before sending it in an event.  It does this by packing the defined bits together and then shifting them to bit 0. In this example you would receive a 4 bit bus using bits 0-3 of the data field in the event.
Full and Hybrid plug-ins can define channel-select options of their own to allow the user to assign additional channels to the plug-in.  When you use these, you will receive RAW DATA events whenever ANY of your assigned channels transition.  Your plug-in must then extract the bits of interest and normalize them for your own use. The framework provides 2 routines to help with this:

uint64 pack(uint64 dat, uint64 mask, uint64 HighBit, uint64 LowBit)

This does the data extraction, bit packing and shifting needed to normalize a given signal's data.  You pass the signal's data mask (returned from the channelselect configuration option) and the current raw data sample.  It returns the signal's bits, packed together and 0-bit justified.  The remaining parameters are the highest and lowest set bits in the data mask.  These should be pre-calculated from the data mask, ONCE during initialization.  Since pack is called hundreds of thousands of times pre signal per capture, performance is improved by pre-calculating these limits and then having the pack routine limit its work to this range.

void FindChannelLimits(uint64 mask, uint64 &HighestBit, uint64 &LowestBit)

This is an optimization helper.  During configuration, you can use this to pre-calculate the highest and lowest bit positions used in a data mask.  These are then passed to the pack routine each time you need to extract a given signal's data. You pass the datamask (from a channel select option) and references to the HighestBit and LowestBit variables.