ROCKM FIFO library - rockmfifo

This module implements advanced access to the FIFO. The FIFO can be read out as raw data or as frames.

For this reason a cache of the FIFO is needed.

So, if you use this module, do not read the FIFO in any other way! Stange things may (will) happen.

Index:

FIFO id
Initialization routines
Set cache
Check if FIFO empty
Raw read
Frame read
Conversion routines
Cache manipulation routines
Error codes
List of types and routines

FIFO id

The access to the FIFO is implemented via channels. Each channel have its own FIFO id. In this way one application can access many different FIFOs simply using different ids.

The definition of the FIFO id type:

ROCKM_FIFO_id

This is a primitive type so the access to the internal stucture should not be done.

All the routines present in rockmfifo have a parameter of this type.

Initialization routines

As stated before, the access to a FIFO is implemented via a FIFO id. To obtain such an id you have to open a channel to the FIFO using rockm_fifo_open. This id will than be used for all the accesses to the FIFO.
Each id must identify a different FIFO.

When you finish using the FIFO, please call rock_close to close the channel associated to the id.

Follows the descriptions of the functions:

rockm_fifo_open()

Associates a FIFO id to a FIFO.
Must be called before any access to the FIFO.

Syntax:

#define rockm_fifo_open(/* ROCK_id */ rock_id,/* unsigned char */ cancache,/*ROCKM_FIFO_id * */ fifo_id);

Parameters:

IN : rockm_id: a ROCKM id, see rockm library module
IN : cancache: type of cache, see set cache section
OUT: fifo_id: pointer to a new FIFO id

Returns:

ROCKM_ERROR_OK in case of success

rockm_fifo_close()

Disposes the FIFO id.
Should be called after the last FIFO access.

Syntax:

int rockm_fifo_close(ROCKM_FIFO_id fifo_id,ROCKM_FIFO_RAW *cache);

Parameters:

IN: fifo_id: FIFO id
OUT: cache: unused cache data
see the raw read section for details about ROCKM_FIFO_RAW

Returns:

ROCKM_ERROR_OK in case of success

Set cache

As stated before, this module uses a cache to manage the frames. This routine sets/changes the cache policy.

rockm_fifo_set_cancache()

Syntax:

int rockm_fifo_set_cancache(ROCKM_FIFO_id fifo_id,unsigned char cancache);

Parameters:

IN: fifo_id

FIFO id

IN: cancache

new cache policy

ROCKM_FIFO_CACHE_OFF: disable read ahead caching
ROCKM_FIFO_CACHE_MINIMAL: read more only if the FIFO is at least half full
ROCKM_FIFO_CACHE_ADVANCED: read until not empty
ROCKM_FIFO_CACHE_BLOCK: force block transfer, read more only if the FIFO is at least half full
ROCKM_FIFO_CACHE_BLOCK_ADVANCED: forse block transfer, read all the FIFO

Returns:

ROCKM_ERROR_OK in case of success

Check if FIFO empty

Cause the cache, you cannot query hardware for FIFO empty. Use this function instead.

rockm_fifo_isnotempty()

Syntax:

int rockm_fifo_isnotempty(ROCKM_FIFO_id fifo_id);

Parameters:

IN: fifo_id: FIFO id

Returns:

ROCKM_ERROR_OK if not empty
ROCKM_ERROR_FIFO_EMPTY if empty

Raw read

The more simple operation you can do on the FIFO is read-out one or more elements. This is the raw read.

rockm_fifo_raw_read()

Syntax:

int rockm_fifo_raw_read(ROCKM_FIFO_id fifo_id, unsigned int *data);

Parameters:

IN: fifo_id: FIFO id
OUT: data: read data if FIFO not empty

Returns:

ROCKM_ERROR_OK in case of success
ROCKM_ERROR_FIFO_EMPTY if FIFO empty

rockm_fifo_raw_blockread()

Syntax:

int rockm_fifo_raw_blockread(ROCKM_FIFO_id fifo_id, unsigned int nrels, ROCKM_FIFO_RAW *data);
int rockm_fifo_raw_blockread_bits(ROCKM_FIFO_id fifo_id, unsigned int nrels, ROCKM_FIFO_RAW_bits *data);

Parameters:

IN: fifo_id: FIFO id
IN: nrels: nr. of elements you want to be read
OUT: data: array of elements

Returns:

ROCKM_ERROR_OK in case of success
ROCKM_ERROR_FIFO_EMPTY if less than nrels elements were read

Follows the raw read specific type:

ROCKM_FIFO_RAW

Frame read

Reading raw elements can be usefull, but normally we are interested in frames. This is the frame read.

rockm_fifo_frame_read()

Syntax:

int rockm_fifo_frame_read(ROCKM_FIFO_id fifo_id, ROCKM_FIFO_FRAME *data);

Parameters:

IN: fifo_id: FIFO id
OUT: data: read frame if everything OK or a parity error error happened

Returns:

ROCKM_ERROR_OK in case of success (frame read)
ROCKM_ERROR_FIFO_EMPTY if FIFO was empty before the full frame was read
ROCKM_ERROR_FIFO_FRAME_SUPER_HEADER if there is an error in the frame
ROCKM_ERROR_FIFO_FRAME_SUB_HEADER if there is an error in the frame
ROCKM_ERROR_FIFO_FRAME_SLAVE if there is an error in the frame
ROCKM_ERROR_FIFO_FRAME_SUB_FOOTER if there is an error in the frame
ROCKM_ERROR_FIFO_FRAME_SUPER_FOOTER if there is an error in the frame
ROCKM_ERROR_FIFO_FRAME_PARITY if there is a parity error (frame read)
ROCKM_ERROR_FIFO_FRAME_TRIGGER if there is a trigger error (frame read)
ROCKM_ERROR_FIFO_FRAME_LAST if there is a last bit error (frame read)
ROCKM_ERROR_FIFO_FRAME_COUNTER if there is a counter error (frame read)
ROCKM_ERROR_FIFO_FRAME_OVERFLOW if the frame is to big

rockm_fifo_frame_blockread()

Syntax:

int rockm_fifo_frame_blockread(ROCKM_FIFO_id fifo_id, unsigned int nrels, ROCKM_FIFO_FRAMEs *data);

Parameters:

IN: fifo_id: FIFO id
IN: nrels: nr. of elements you want to be read
OUT: data: list of frames

Returns:

ROCKM_ERROR_OK in case of success
ROCKM_ERROR_FIFO_EMPTY if less than nrels elements were read
ROCKM_ERROR_FIFO_FRAME_SUPER_HEADER if there is an error in a frame
ROCKM_ERROR_FIFO_FRAME_SUB_HEADER if there is an error in a frame
ROCKM_ERROR_FIFO_FRAME_SLAVE if there is an error in a frame
ROCKM_ERROR_FIFO_FRAME_SUB_FOOTER if there is an error in a frame
ROCKM_ERROR_FIFO_FRAME_SUPER_FOOTER if there is an error in a frame
ROCKM_ERROR_FIFO_FRAME_TRIGGER if there is a trigger error (frame read)
ROCKM_ERROR_FIFO_FRAME_LAST if there is a last bit error (frame read)
ROCKM_ERROR_FIFO_FRAME_COUNTER if there is a counter error (frame read)
ROCKM_ERROR_FIFO_FRAME_OVERFLOW if a frame is to big

Note:

Parity errors are not reported.

rockm_fifo_frame_rawread()

The previous routines returns formated data. It is usefull most of the time, but if you have to save such data, you are in trouble. The following routines read a complete frame but do not format it.

Syntax:

int rockm_fifo_frame_rawread(ROCKM_FIFO_id fifo_id, ROCKM_FIFO_RAW *data);
int rockm_fifo_frame_rawread_bits(ROCKM_FIFO_id fifo_id, ROCKM_FIFO_RAW_bits *data);

Parameters:

IN: fifo_id: FIFO id
OUT: data: read frame if everything OK or a parity error error happened

Returns:

rockm_fifo_frame_synch()

When a frame is faulty (except for the parity error), the other four frame read routines report the error, but do not read the faulty frame. This routine read the FIFO until a header is found. (first excluded)

Syntax:

int rockm_fifo_frame_synch(ROCKM_FIFO_id fifo_id, ROCKM_FIFO_RAW *data);

Parameters:

IN: fifo_id: FIFO id
OUT: data: array of elements

Returns:

ROCKM_ERROR_OK in case of success
ROCKM_ERROR_FIFO_EMPTY if the FIFO went empty before a header was found

Follows the frame read specific types:

Conversion routines

As you can read in the frame read section, a frame can be read out in formatted or in raw mode.

This routines converts from one to another, giving the user complete freedom.

rockm_fifo_frame_conv_frame2raw()

This routine converts formatted data to raw one.

Syntax:

int rockm_fifo_conv_frame2raw(ROCKM_FIFO_FRAME indata, ROCKM_FIFO_RAW *outdata);

Parameters:

IN: indata: formatted data
OUT: outdata: raw data

Returns:

ROCKM_ERROR_OK in case of success

rockm_fifo_frame_conv_raw2frame()

This routines convert raw data to formatted one.

Syntax:

int rockm_fifo_conv_raw2frame(ROCKM_FIFO_RAW indata, ROCKM_FIFO_FRAME *outdata);

Parameters:

IN: indata: raw data
OUT: outdata: formatted data

Returns:

ROCKM_ERROR_OK in case of success (frame converted)
ROCKM_ERROR_FIFO_EMPTY if indata ends before the full frame was read
ROCKM_ERROR_FIFO_FRAME_SUPER_HEADER if there is an error in the frame
ROCKM_ERROR_FIFO_FRAME_SUB_HEADER if there is an error in the frame
ROCKM_ERROR_FIFO_FRAME_SLAVE if there is an error in the frame
ROCKM_ERROR_FIFO_FRAME_SUB_FOOTER if there is an error in the frame
ROCKM_ERROR_FIFO_FRAME_SUPER_FOOTER if there is an error in the frame
ROCKM_ERROR_FIFO_FRAME_PARITY if there is a parity error (frame converted)
ROCKM_ERROR_FIFO_FRAME_TRIGGER if there is a trigger error (frame converted)
ROCKM_ERROR_FIFO_FRAME_LAST if there is a last bit error (frame converted)
ROCKM_ERROR_FIFO_FRAME_COUNTER if there is a counter error (frame converted)