Subversion Repositories openrisc

    Overview

    Overview

    eCos Support for Analog/Digital Converters

ADC support in eCos is based around the standard character device

interface. Hence all device IO function, or file IO functions may be

used to access ADC devices.

ADC devices are presented as read-only serial channels that generate

samples at a given rate. The size of each sample is hardware specific

and is defined by the cyg_adc_sample_t type. The sample

rate may be set at runtime by the application. Most ADC devices

support several channels which are all sampled at the same

rate. Therefore setting the rate for one channel will usually change

the rate for all channels on that device.

The use of the ADC devices is best shown by example.  The following is

a simple example of using the eCos device interface to access the ADC:

        int res;

        cyg_io_handle_t handle;

        // Get a handle for ADC device 0 channel 0

        res = cyg_io_lookup( "/dev/adc00", &handle );

        if( res != ENOERR )

            handle_error(err);

        for(;;)

        {

            cyg_adc_sample_t sample;

            cyg_uint32 len = sizeof(sample);

            // read a sample from the channel

            res = cyg_io_read( handle, &sample, &len );

            if( res != ENOERR )

                handle_error(err);

            use_sample( sample );

        }

In this example, the required channel is looked up and a handle on it

acquired. Conventionally ADC devices are named "/dev/adcXY" where X is

the device number and Y the channel within that device. Following

this, samples are read from the device sequentially.

ADC devices may also be accessed using FILEIO operations. These allow

more sophisticated usage. The following example shows

select() being used to gather samples from several devices.

        int fd1, fd2;

        // open channels, non-blocking

        fd1 = open( "/dev/adc01", O_RDONLY|O_NONBLOCK );

        fd2 = open( "/dev/adc02", O_RDONLY|O_NONBLOCK );

        if( fd1 < 0 || fd2 < 0 )

            handle_error( errno );

        for(;;)

        {

            fd_set rd;

            int maxfd = 0;

            int err;

            cyg_adc_sample_t samples[128];

            int len;

            FD_ZERO( &rd );

            FD_SET( fd1, &rd );

            FD_SET( fd2, &rd );

            maxfd = max(fd1,fd2);

            // select on available data on each channel.

            err = select( maxfd+1, &rd, NULL, NULL, NULL );

            if( err < 0 )

                handle_error(errno);

            // If channel 1 has data, handle it

            if( FD_ISSET( fd1, &rd ) )

            {

                len = read( fd1, &samples, sizeof(samples) );

                if( len > 0 )

                    handle_samples_chan1( &samples, len/sizeof(sample[0]) );

            }

            // If channel 2 has data, handle it

            if( FD_ISSET( fd2, &rd ) )

            {

                len = read( fd2, &samples, sizeof(samples) );

                if( len > 0 )

                    handle_samples_chan2( &samples, len/sizeof(sample[0]) );

            }

        }

This test uses FILEIO operations to access ADC channels. It starts by

opening two channels for reading only and with blocking disabled. It

then falls into a loop using select to wake up whenever either channel

has samples available.

As indicated, the main interface to ADC devices is via the standard

character device interface. However, there are a number of aspects

that are ADC specific.

Samples can vary in size depending on the underlying hardware and is

often a non-standard number of bits. The actual number of bits is

defined by the hardware driver package, and the generic ADC package

uses this to define a type cyg_adc_sample_t which can

contain at least the required number of bits. All reads from an ADC

channel should be expressed in multiples of this type, and actual

bytes read will also always be a multiple.

The sample rate of an ADC device can be varied by calling a

set_config function, either at the device IO API

level or at the FILEIO level. The following two functions show how

this is done at each:

int set_rate_io( cyg_io_handle_t handle, int rate )

{

    cyg_adc_info_t info;

    cyg_uint32 len = sizeof(info);

    info.rate = rate;

    return cyg_io_set_config( handle,

                              CYG_IO_SET_CONFIG_ADC_RATE,

                              &info,

                              &len);

}

int set_rate_fileio( int fd, int rate )

{

    cyg_adc_info_t info;

    info.rate = rate;

    return cyg_fs_fsetinfo( fd,

                            CYG_IO_SET_CONFIG_ADC_RATE,

                            &info,

                            sizeof(info) );

}

Channels are initialized in a disabled state and generate no

samples. When a channel is first looked up or opened, then it is

automatically enabled and samples start to accumulate. A channel may

then be disable or re-enabled via a set_config

function:

int disable_io( cyg_io_handle_t handle )

{

    return cyg_io_set_config( handle,

                              CYG_IO_SET_CONFIG_ADC_DISABLE,

                              NULL,

                              NULL);

}

int enable_io( cyg_io_handle_t handle )

{

    return cyg_io_set_config( handle,

                              CYG_IO_SET_CONFIG_ADC_ENABLE,

                              NULL,

                              NULL);

}

In some particular cases, user might require to flush the ADC data buffer. Flushing

may be perfomed via a set_config

function:

int flush_io( cyg_io_handle_t handle )

{

    return cyg_io_set_config( handle,

                              CYG_IO_SET_CONFIG_ADC_DATA_FLUSH,

                              NULL,

                              NULL);

}

The ADC package defines a number of generic configuration options that

apply to all ADC implementations:

cdl_component CYGPKG_IO_ADC_DEVICES

This option enables the hardware device drivers for the current

platform. ADC devices will only be enabled if this option is itself

enabled.

cdl_option CYGNUM_IO_ADC_SAMPLE_SIZE

This option defines the sample size for the ADC devices.  Given in

bits, it will be rounded up to 8, 16 or 32 to define the

cyg_adc_sample_t type. This option is usually set by the

hardware device driver.

cdl_option CYGPKG_IO_ADC_SELECT_SUPPORT

This option enables support for the select() API

function on all ADC devices. This option can be disabled if the

select() is not used, saving some code and data

space.

In addition to the generic options, each hardware device driver

defines some parameters for each device and channel. The exact names

of the following option depends on the hardware device driver, but

options of this form should be available in all drivers.

cdl_option CYGDAT_IO_ADC_EXAMPLE_CHANNELN_NAME

This option specifies the name of the device for an ADC

channel. Channel names should be of the form "/dev/adcXY" where X is

the device number and Y the channel within that device.

cdl_option CYGNUM_IO_ADC_EXAMPLE_CHANNELN_BUFSIZE

This option specifies the buffer size for an ADC channel. The value is

expressed in multiples of cyg_adc_sample_t rather than

bytes. The default value is 128.

cdl_option CYGNUM_IO_ADC_EXAMPLE_DEFAULT_RATE

This option defines the initial default sample rate for all

channels. The hardware driver may place constraints on the range of

values this option may take.

    ADC Device Drivers

    Overview

    ADC Device Drivers

This section describes how to write an ADC hardware device. While

users of ADC devices do not need to read it, it may provide added

insight into how the devices work.

An ADC hardware driver is represented by a number of data

structures. These are generic device and

channel data structures, a driver private device

data structure, a generic character device table entry and a driver

function table. Most of these structures are instantiated using

macros, which will be described here.

The data structure instantiation for a typical single device, four

channel ADC would look like this:

//==========================================================================

// Instantiate data structures

// -------------------------------------------------------------------------

// Driver functions:

CYG_ADC_FUNCTIONS( example_adc_funs,

                   example_adc_enable,

                   example_adc_disable,

                   example_adc_set_rate );

// -------------------------------------------------------------------------

// Device instance:

static example_adc_info example_adc_info0 =

{

    .base               = CYGARC_HAL_EXAMPLE_ADC_BASE,

    .vector             = CYGNUM_HAL_INTERRUPT_ADC

};

CYG_ADC_DEVICE( example_adc_device,

                &example_adc_funs,

                &example_adc_info0,

                CYGNUM_IO_ADC_EXAMPLE_DEFAULT_RATE );

// -------------------------------------------------------------------------

// Channel instances:

#define EXAMPLE_ADC_CHANNEL( __chan )                                    \

CYG_ADC_CHANNEL( example_adc_channel##__chan,                            \

                 __chan,                                                 \

                 CYGNUM_IO_ADC_EXAMPLE_CHANNEL##__chan##_BUFSIZE,        \

                 &example_adc_device );                                  \

                                                                         \

DEVTAB_ENTRY( example_adc_channel##__chan##_device,                      \

              CYGDAT_IO_ADC_EXAMPLE_CHANNEL##__chan##_NAME,              \

              0,                                                         \

              &cyg_io_adc_devio,                                         \

              example_adc_init,                                          \

              example_adc_lookup,                                        \

              &example_adc_channel##__chan );

EXAMPLE_ADC_CHANNEL( 0 );

EXAMPLE_ADC_CHANNEL( 1 );

EXAMPLE_ADC_CHANNEL( 2 );

EXAMPLE_ADC_CHANNEL( 3 );

The macro CYG_ADC_FUNCTIONS() instantiates a

function table called example_adc_funs and

populates it with the ADC driver functions (see later for details).

Then an instance of the driver private device data structure is

instantiated. In addition to the device base address and interrupt

vector shown here, this stucture should contain the interrupt object

and handle for attaching to the vector. It may also contain any other

variables needed to manage the device.

The macro CYG_ADC_DEVICE() instantiates a

cyg_adc_device structure, named

example_adc_device which will contain pointers to

the function table and private data structure. The initial sample rate

is also supplied here.

For each channel, an ADC channel structure and a device table entry

must be created. The macro EXAMPLE_ADC_CHANNEL() is

defined to simplify this process. The macro

CYG_ADC_CHANNEL defines a

cyg_adc_channel structure, which contains the

channel number, the buffer size, and a pointer to the device object

defined earlier. The call to DEVTAB_ENTRY()

generates a device table entry containing the configured channel name,

a pointer to a device function table defined in the generic ADC

driver, pointers to init and lookup functions implemented here, and a

pointer to the channel data structure just defined.

Finally, four channels, numbered 0 to 3 are created.

There are several classes of function that need to be defined in an

ADC driver. These are those function that go into the channel's device

table, those that go into the ADC device's function table, calls that

the driver makes into the generic ADC package, and interrupt handling

functions.

These functions are placed in the standard device table entry for each

channel and handle initialization and location of the device within

the generic driver infrastructure.

static bool example_adc_init(struct cyg_devtab_entry *tab)

This function is called from the device IO infrastructure to

initialize the device. It should perform any work needed to start up

the device, short of actually starting the generation of samples. This

function will be called for each channel, so if there is

initialization that only needs to be done once, such as creating an

interrupt object, then care should be taken to do this. This function

should also call cyg_adc_device_init() to

initialize the generic parts of the driver.

static Cyg_ErrNo example_adc_lookup(struct cyg_devtab_entry **tab, struct cyg_devtab_entry *sub_tab, const char *name)

This function is called when a client looks up or opens a channel. It

should call cyg_adc_channel_init() to initialize

the generic part of the channel. It should also perform any operations

needed to start the channel generating samples.

These are the functions installed into the driver function table by

the CYG_ADC_FUNCTIONS() macro.

static void example_adc_enable( cyg_adc_channel *chan )

This function is called from the generic ADC package to enable the

channel in response to a

CYG_IO_SET_CONFIG_ADC_ENABLE config operation. It

should take any steps needed to start the channel generating samples.

static void example_adc_disable( cyg_adc_channel *chan )

This function is called from the generic ADC package to enable the

channel in response to a

CYG_IO_SET_CONFIG_ADC_DISABLE config operation. It

should take any steps needed to stop the channel generating samples.

static void example_adc_set_rate( cyg_adc_channel *chan, cyg_uint32 rate )

This function is called from the generic ADC package to enable the

channel in response to a CYG_IO_SET_CONFIG_ADC_RATE

config operation. It should take any steps needed to change the sample

rate of the channel, or of the entire device.

These functions are called by a hardware ADC device driver to perform

operations in the generic ADC package.

__externC void cyg_adc_device_init( cyg_adc_device *device )

This function is called from the driver's init function and is used to

initialize the cyg_adc_device object.

__externC void cyg_adc_channel_init(cyg_adc_channel *chan)

This function is called from the driver's lookup function and is used

to initialize the cyg_adc_channel object.

__externC cyg_uint32 cyg_adc_receive_sample(cyg_adc_channel *chan, cyg_adc_sample_t sample)

This function is called from the driver's ISR to add a new sample to

the buffer. The return value will be either zero, or

CYG_ISR_CALL_DSR and should be ORed with the return

value of the ISR.

__externC void cyg_adc_wakeup(cyg_adc_channel *chan )

This function is called from the driver's DSR to cause any threads

waiting for data to wake up when a new sample is available. It should

only be called if the wakeup field of the

channel object is true.

These functions are internal to the driver, but make calls on generic

package functions. Typically an ADC device will have a single

interrupt vector with which it signals available samples on the

channels and any error conditions such as overruns.

static cyg_uint32 example_adc_isr(cyg_vector_t vector, cyg_addrword_t data)

This function is the ISR attached to the ADC device's interrupt

vector. It is responsible for reading samples from the channels and

passing them on to the generic layer. It needs to check each channel

for data, and call cyg_adc_receive_sample() for

each new sample available, and then ready the device for the next

interrupt.  It's activities are best explained by example:

static cyg_uint32 example_adc_isr(cyg_vector_t vector, cyg_addrword_t data)

{

    cyg_adc_device *example_device = (cyg_adc_device *) data;

    example_adc_info *example_info = example_device->dev_priv;

    cyg_uint32 res = 0;

    int i;

    // Deal with errors if necessary

    DEVICE_CHECK_ERRORS( example_info );

    // Look for all channels with data available

    for( i = 0; i < CHANNEL_COUNT; i++ )

    {

        if( CHANNEL_SAMPLE_AVALIABLE(i) )

        {

            // Fetch data from this channel and pass up to higher

            // level.

            cyg_adc_sample_t data = CHANNEL_GET_SAMPLE(i);

            res |= CYG_ISR_HANDLED | cyg_adc_receive_sample( example_info->channel[i], data );

        }

    }

   // Clear any interrupt conditions

    DEVICE_CLEAR_INTERRUPTS( example_info );

    cyg_drv_interrupt_acknowledge(example_info->vector);

    return res;

}

static void example_adc_dsr(cyg_vector_t vector, cyg_ucount32 count, cyg_addrword_t data)

This function is the DSR attached to the ADC device's interrupt

vector. It is called by the kernel if the ISR return value contains

the CYG_ISR_HANDLED bit. It needs to call

cyg_adc_wakeup() for each channel that has its

wakeup field set. Again, and example should

make it all clear:

static void example_adc_dsr(cyg_vector_t vector, cyg_ucount32 count, cyg_addrword_t data)

{

    cyg_adc_device *example_device = (cyg_adc_device *) data;

    example_adc_info *example_info = example_device->dev_priv;

    int i;

    // Look for all channels with pending wakeups

    for( i = 0; i < CHANNEL_COUNT; i++ )

    {

        if( example_info->channel[i]->wakeup )

            cyg_adc_wakeup( example_info->channel[i] );

    }

}