All devices have a name. The standard provided devices use names such as “/dev/console” and “/dev/serial0”, where the “/dev/” prefix indicates that this is the name of a device.
cyg_io_lookup() function:
used to map that name onto the handle for the device.Aslo, the cyg_io_lookup() function provides drivers the opportunity to initialize the device when usage actually starts.
All functions return a value of the type Cyg_ErrNo. If an error condition is detected, this value will be negative and the absolute value indicates the actual error, as specified in cyg/error/codes.h.
The only other legal return value will be ENOERR. All other function arguments are pointers (references).
There are some funtions you must will use it:
// Lookup a device and return its handle Cyg_ErrNo cyg_io_lookup( const char *name, cyg_io_handle_t *handle ) |
This function maps a device name onto an appropriate handle. If the named device is not in the system, then the error -ENOENT is returned. If the device is found, then the handle for the device is returned by way of the handle pointer *handle.
// Write data to a device Cyg_ErrNo cyg_io_write( cyg_io_handle_t handle, const void *buf, cyg_uint32 *len ) |
This function sends data to a device. The size of data to send is contained in *len and the actual size sent will be returned in the same place.
// Read data from a device Cyg_ErrNo cyg_io_read( cyg_io_handle_t handle, void *buf, cyg_uint32 *len ) |
This function receives data from a device. The desired size of data to receive is contained in *len and the actual size obtained will be returned in the same place.
// Get the configuration of a device Cyg_ErrNo cyg_io_get_config( cyg_io_handle_t handle, cyg_uint32 key, void *buf, cyg_uint32 *len ) |
This function is used to obtain run-time configuration about a device. The type of information retrieved is specified by the key. The data will be returned in the given buffer. The value of *len should contain the amount of data requested, which must be at least as large as the size appropriate to the selected key. The actual size of data retrieved is placed in *len. The appropriate key values differ for each driver and are all listed in the file <cyg/io/config_keys.h>.
// Change the configuration of a device Cyg_ErrNo cyg_io_set_config( cyg_io_handle_t handle, cyg_uint32 key, const void *buf, cyg_uint32 *len ) |
This function is used to manipulate or change the run-time configuration of a device. The type of information is specified by the key. The data will be obtained from the given buffer. The value of *len should contain the amount of data provided, which must match the size appropriate to the selected key. The appropriate key values differ for each driver and are all listed in the file <cyg/io/config_keys.h>.
Two different classes of serial drivers are provided as a standard part of the eCos system. These are described as “raw serial” (serial) and “tty-like” (tty).
Runtime Configuration
Runtime configuration is achieved by exchanging data structures with the driver via the cyg_io_set_config() and cyg_io_get_config() functions.
typedef struct { cyg_serial_baud_rate_t baud; cyg_serial_stop_bits_t stop; cyg_serial_parity_t parity; cyg_serial_word_length_t word_length; cyg_uint32 flags; } cyg_serial_info_t; |
The field word_length contains the number of data bits per word (character). This must be one of the values:
CYGNUM_SERIAL_WORD_LENGTH_5 CYGNUM_SERIAL_WORD_LENGTH_6 CYGNUM_SERIAL_WORD_LENGTH_7 CYGNUM_SERIAL_WORD_LENGTH_8 |
The field baud contains a baud rate selection. This must be one of the values:
CYGNUM_SERIAL_BAUD_50 CYGNUM_SERIAL_BAUD_75 CYGNUM_SERIAL_BAUD_110 CYGNUM_SERIAL_BAUD_134_5 CYGNUM_SERIAL_BAUD_150 CYGNUM_SERIAL_BAUD_200 CYGNUM_SERIAL_BAUD_300 CYGNUM_SERIAL_BAUD_600 CYGNUM_SERIAL_BAUD_1200 CYGNUM_SERIAL_BAUD_1800 CYGNUM_SERIAL_BAUD_2400 CYGNUM_SERIAL_BAUD_3600 CYGNUM_SERIAL_BAUD_4800 CYGNUM_SERIAL_BAUD_7200 CYGNUM_SERIAL_BAUD_9600 CYGNUM_SERIAL_BAUD_14400 CYGNUM_SERIAL_BAUD_19200 CYGNUM_SERIAL_BAUD_38400 CYGNUM_SERIAL_BAUD_57600 CYGNUM_SERIAL_BAUD_115200 CYGNUM_SERIAL_BAUD_234000 |
The field stop contains the number of stop bits. This must be one of the values:
CYGNUM_SERIAL_STOP_1 CYGNUM_SERIAL_STOP_1_5 CYGNUM_SERIAL_STOP_2 |
Note: On most hardware, a selection of 1.5 stop bits is only valid if the word (character) length is 5.
The field parity contains the parity mode. This must be one of the values:
CYGNUM_SERIAL_PARITY_NONE CYGNUM_SERIAL_PARITY_EVEN CYGNUM_SERIAL_PARITY_ODD CYGNUM_SERIAL_PARITY_MARK CYGNUM_SERIAL_PARITY_SPACE |
The field flags is a bitmask which controls the behavior of the serial device driver. It should be built from the values CYG_SERIAL_FLAGS_xxx defined below:
#define CYG_SERIAL_FLAGS_RTSCTS 0x0001 |
If this bit is set then the port is placed in “hardware handshake” mode. In this mode, the CTS and RTS pins control when data is allowed to be sent/received at the port. This bit is ignored if the hardware does not support this level of handshake.
typedef struct { cyg_int32 rx_bufsize; cyg_int32 rx_count; cyg_int32 tx_bufsize; cyg_int32 tx_count; } cyg_serial_buf_info_t; |
The field rx_bufsize contains the total size of the incoming data buffer. This is set to zero on devices that do not support buffering (i.e. polled devices).
The field rx_count contains the number of bytes currently occupied in the incoming data buffer. This is set to zero on devices that do not support buffering (i.e. polled devices).
The field tx_bufsize contains the total size of the transmit data buffer. This is set to zero on devices that do not support buffering (i.e. polled devices).
The field tx_count contains the number of bytes currently occupied in the transmit data buffer. This is set to zero on devices that do not support buffering (i.e. polled devices).
API Detailscyg_io_writecyg_io_read
cyg_io_write(handle, buf, len) |
Send the data from buf to the device. The driver maintains a buffer to hold the data. The size of the intermediate buffer is configurable within the interface module. The data is not modified at all while it is being buffered. On return, *len contains the amount of characters actually consumed .
It is possible to configure the write call to be blocking (default) or non-blocking. Non-blocking mode requires both the configuration option CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING to be enabled, and the specific device to be set to non-blocking mode for writes (see cyg_io_set_config()).
In blocking mode, the call will not return until there is space in the buffer and the entire contents of buf have been consumed.
In non-blocking mode, as much as possible gets consumed from buf. If everything was consumed, the call returns ENOERR. If only part of the buf contents was consumed, -EAGAIN is returned and the caller must try again. On return, *len contains the number of characters actually consumed .
The call can also return -EINTR if interrupted via the cyg_io_get_config()/ABORT key.
cyg_io_read(handle, buf, len) |
Receive data into the buffer, buf, from the device. No manipulation of the data is performed before being transferred. An interrupt driven interface module will support data arriving when no read is pending by buffering the data in the serial driver. Again, this buffering is completely configurable. On return, *len contains the number of characters actually received.
It is possible to configure the read call to be blocking (default) or non-blocking. Non-blocking mode requires both the configuration option CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING to be enabled, and the specific device to be set to non-blocking mode for reads (see cyg_io_set_config()).
In blocking mode, the call will not return until the requested amount of data has been read.
In non-blocking mode, data waiting in the device buffer is copied to buf, and the call returns immediately. If there was enough data in the buffer to fulfill the request, ENOERR is returned. If only part of the request could be fulfilled, -EAGAIN is returned and the caller must try again. On return, *len contains the number of characters actually received.
The call can also return -EINTR if interrupted via the cyg_io_get_config()/ABORT key.