ROCK L1 library - rock

This is the module a typical application will use.

The ROCK is presented as a list of fields, with the possibility of a block read of a register, a block write of a register, a block read of a page and a block read of a FIFO.

Uses the L0 library modules rockhard and rockbits.

Index

ROCK id
Query ROCK presence
Initialization routines
Get a field
Set a field
Block read of a register
Block write of a register
Block read of a page
Block read of a FIFO
Register and page types
Examples
List of types and routines

ROCK id

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

The definition of the ROCK id type:

ROCK_id

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

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

Note:

ROCK id is the same as ROCK hardware id and can be used in the rockhard module.

Query ROCK presence

A typical application do not know which ROCKs are currenty present. This routine helps to find them out.

rock_ispresent()

Syntax:

#define rock_ispresent(/*int*/ chain, /*int*/ crate);

Parameters:

IN: chain: VIC chain
IN: crate: position in the VIC chain

Returns:

0 if the ROCK is not present, 1 else

NOTE:

Calls directly rockh_ispresent.

Initialization routines

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

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

Follows the descriptions of the functions:

rock_open()

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

Syntax:

#define rock_open(/*int*/ chain, /*int*/ crate, /*ROCK_id * */ rock_id);

Parameters:

IN: chain: VIC chain
IN: crate: position in the VIC chain
OUT: rock_id: pointer to a new ROCK id

Returns:

ROCK_ERROR_OK in case of success

NOTE:

Calls directly rockh_open.

rock_close()

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

Syntax:

#define rock_close(/*ROCK_id*/ rock_id);

Parameters:

IN: rock_id: ROCK id

Returns:

ROCK_ERROR_OK in case of success

NOTE:

Calls directly rockh_close.

Get a field

At this level the ROCK is presented as a list of fields. Use the get routines to read this fields.

The general form of a get routine is:

Follows the list of the get routines:

Set a field

As stated before, the ROCK is presented as a list of fields. Use the set routines to set this fields.

The general form of a set routine is:

Follows the list of the set routines:

Block read of a register

Reading the rock field by field is very usefull, but fisicaly the ROCK is made of registers. So if an application needs to fields from the same register, the library will access the ROCK two times. This can symply create overhead, but can also create inconsistency between the two reads. To avoid this problems, use the register read routines.

More, some fields have not even sense if not read with the rest of a register. This fields have no corresponding get field routine.

The general form of a register read routine is:

Follows the list of register read specific types and the register read routines:

Block read of a register

As with register read routines, setting filed by field can generate some problems. So, If you have to set more than one field, use the register write routines.

The general form of a register write routine is:

Syntax:

#define rock_write_<register>(/*ROCK_id */ rock_id, /*ROCK_<REGISTER>_bits*/ bits)

Parameters:

IN: rock_id: ROCK id
IN: bits: the record of fields with values to be written

Returns:

ROCK_ERROR_OK in case of success
ROCK_ERROR_TEST if the record was not written correctly

Note:

Not all the registers can be written-in at any time. See the ROCK documentation for details.

The routines are implemented as macros.

Follows the list of register read specific types and the register read routines:

Block read of a page

As stated describing register read routines, reading field by field can generate some problems. So, if you have to read a large number of fields, read an entire page and the examine the fields you are interested in.

The general form of a page read routine is:

Syntax:

#define rock_readpage_<register>(/*ROCK_id */ rock_id, /*ROCK_PAGE_<PAGE>_bits*/ bits)

Parameters: