ROCK L2 library - rockfifo

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.

Uses the L0 library modules rockbits, rockhard, rockframes and the L1 library module rock.

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:

ROCK_FIFO_id

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

All the routines present in rockfifo 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 rock_fifo_open_<what>. 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:

rock_fifo_open_dfifo() rock_fifo_open_efifo()

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

Syntax:

#define rock_fifo_open_<what>(/* ROCK_id */ rock_id,/* unsigned char */ cancache,/*ROCK_FIFO_id * */ fifo_id);

Parameters:

IN : rock_id: a ROCK id, see rock library module
IN : cancache: type of cache, see set cache section
OUT: fifo_id: pointer to a new FIFO id

Returns:

ROCK_ERROR_OK in case of success

rock_fifo_close()

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

Syntax:

int rock_fifo_close(ROCK_FIFO_id fifo_id,ROCK_FIFO_RAW_bits *cache);

Parameters:

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

Returns:

ROCK_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.

rock_fifo_set_cancache()

Syntax:

int rock_fifo_set_cancache(ROCK_FIFO_id fifo_id,unsigned char cancache);

Parameters:

IN: fifo_id

FIFO id

IN: cancache

new cache policy

ROCK_FIFO_CACHE_OFF: disable read ahead caching
ROCK_FIFO_CACHE_MINIMAL: read more only if the FIFO is at least half full
ROCK_FIFO_CACHE_ADVANCED: read until not empty
ROCK_FIFO_CACHE_BLOCK: force block transfer, read more only if the FIFO is at least half full
ROCK_FIFO_CACHE_BLOCK_ADVANCED: forse block transfer, read all the FIFO

Returns:

ROCK_ERROR_OK in case of success

Check if FIFO empty

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

rock_fifo_isnotempty()

Syntax:

int rock_fifo_isnotempty(ROCK_FIFO_id fifo_id);

Parameters:

IN: fifo_id: FIFO id

Returns:

ROCK_ERROR_OK if not empty
ROCK_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.

rock_fifo_raw_read() rock_fifo_raw_read_bits()

Syntax:

int rock_fifo_raw_read(ROCK_FIFO_id fifo_id, unsigned int *data);
int rock_fifo_raw_read_bits(ROCK_FIFO_id fifo_id, ROCK_EDFIFO_bits *data);

Parameters:

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

Returns:

ROCK_ERROR_OK in case of success
ROCK_ERROR_FIFO_EMPTY if FIFO empty

rock_fifo_raw_blockread() rock_fifo_raw_blockread_bits()

Syntax:

int rock_fifo_raw_blockread(ROCK_FIFO_id fifo_id, unsigned int nrels, ROCK_FIFO_RAW *data);
int rock_fifo_raw_blockread_bits(ROCK_FIFO_id fifo_id, unsigned int nrels, ROCK_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:

ROCK_ERROR_OK in case of success
ROCK_ERROR_FIFO_EMPTY if less than nrels elements were read

Follows the raw read specific type:

Frame read

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

rock_fifo_frame_read()

Syntax:

int rock_fifo_frame_read(ROCK_FIFO_id fifo_id, ROCK_FIFO_FRAME *data);

Parameters:

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

Returns:

ROCK_ERROR_OK in case of success (frame read)
ROCK_ERROR_FIFO_EMPTY if FIFO was empty before the full frame was read
ROCK_ERROR_FIFO_FRAME_HEADER if there is an error in the frame
ROCK_ERROR_FIFO_FRAME_SLAVE if there is an error in the frame
ROCK_ERROR_FIFO_FRAME_FOOTER if there is an error in the frame
ROCK_ERROR_FIFO_FRAME_PARITY if there is a parity error (frame read)
ROCK_ERROR_FIFO_FRAME_OVERFLOW if the frame is to big

rock_fifo_frame_blockread()

Syntax:

int rock_fifo_frame_blockread(ROCK_FIFO_id fifo_id, unsigned int nrels, ROCK_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:

ROCK_ERROR_OK in case of success
ROCK_ERROR_FIFO_EMPTY if less than nrels elements were read
ROCK_ERROR_FIFO_FRAME_HEADER if there is an error in a frame
ROCK_ERROR_FIFO_FRAME_SLAVE if there is an error in a frame
ROCK_ERROR_FIFO_FRAME_FOOTER if there is an error in a frame
ROCK_ERROR_FIFO_FRAME_OVERFLOW if a frame is to big

Note:

Parity errors are not reported.

rock_fifo_frame_rawread() rock_fifo_frame_rawread_bits()

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 rock_fifo_frame_rawread(ROCK_FIFO_id fifo_id, ROCK_FIFO_RAW *data);
int rock_fifo_frame_rawread_bits(ROCK_FIFO_id fifo_id, ROCK_FIFO_RAW_bits *data);

Parameters:

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

Returns:

rock_fifo_frame_synch() rock_fifo_frame_synch_bits()

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 rock_fifo_frame_synch(ROCK_FIFO_id fifo_id, ROCK_FIFO_RAW *data);
int rock_fifo_frame_synch_bits(ROCK_FIFO_id fifo_id, ROCK_FIFO_RAW_bits *data);

Parameters:

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

Returns:

ROCK_ERROR_OK in case of success
ROCK_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.

rock_fifo_frame_conv_frame2raw()

This routine converts formatted data to raw one.

Syntax:

int rock_fifo_conv_frame2raw(ROCK_FIFO_FRAME indata, ROCK_FIFO_RAW *outdata);

Parameters:

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

Returns:

ROCK_ERROR_OK in case of success

rock_fifo_frame_conv_raw2frame() rock_fifo_frame_conv_raw_bits2frame()

This routines convert raw data to formatted one.

Syntax:

int rock_fifo_conv_raw2frame(ROCK_FIFO_RAW indata, ROCK_FIFO_FRAME *outdata);
int rock_fifo_conv_raw_bits2frame(ROCK_FIFO_RAW_bits indata, ROCK_FIFO_FRAME *outdata);

Parameters:

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

Returns:

ROCK_ERROR_OK in case of success (frame read)
ROCK_ERROR_FIFO_EMPTY if indata ends before the full frame was read
ROCK_ERROR_FIFO_FRAME_HEADER if there is an error in the frame
ROCK_ERROR_FIFO_FRAME_SLAVE if there is an error in the frame
ROCK_ERROR_FIFO_FRAME_FOOTER if there is an error in the frame
ROCK_ERROR_FIFO_FRAME_PARITY if there is a parity error (frame returned)