group::SWITCHBOARD

The switchboard device driver is a device that is used to connect other devices and transfer data in the background.

For example, the switchboard can read data from a UART and write it to a FIFO. It can also implement UART loopback functionality.

It is also well-suited for streaming audio from one interface to another (say from I2S input to a USB audio class endpoint).

The switchboard is configured using ioctl calls.

Reading the switchboard will read a block device populated with the status of the connections.

switchboard_status_t status;

int fd = open("/dev/switchboard", O_RDWR);

while( read(&status, sizeof(status)) > 0 ){
  printf("Connection is active:%d\n", status.o_flags != 0 );
}

When making switchboard connections, one must consider input of the throughput vs input of the output. If the output has a higher throughput than the input, the terminals can be connected directly. For example, a 115200 bps UART could be directly connected to a SPI at 1MHz.

  • UART (ASYNC) -> SPI (ASYNC)

If the output and input have similar or identical throughput values, they should be connected through a fifo rather than directly. This is the approach for I2S to USB.

  • I2S (ASYNC) -> FFIFO (SYNC NON-BLOCKING)
  • FFIFO (SYNC NON-BLOCKING) -> USB (ASYNC)

The FFIFO should be configured to allow overflowing. This ensures that if the USB is slightly slower than the I2S a packet will simply be dropped rather than having the switchboard connection stop on a write error.

The switchboard can also be used to buffer serial slave data in FIFOs. The UART is the best example, where any bytes that arrive are written to a FIFO. But the SPI and I2C can also be configured as slaves connected to FIFOs.

UART (ASYNC) -> FIFO (SYNC NON-BLOCKING)

The application can then poll the FIFO or receive a signal when data arrives.

Adjusting priority must be done with care. Marking an input as high priority will cause writes to the output to be executed in a high priority context. This can cause problems with some drivers that share one interrupt between multiple channels. For example, when connecting:

I2S (High Priority) -> USB (Normal Priority)

the USB will be written with a high priority. This may cause the USB interrupt service routine to be interrupted causing undefined results. The solution is to add a FIFO

I2S (High Priority) -> FFIFO (SYNC NON-BLOCKING) FFIFO (SYNC NON-BLOCKING) -> USB (Normal Priority)

Using this scheme all USB channels are executed at the same priority level.

Details

defineSWITCHBOARD_VERSION


defineSWITCHBOARD_IOC_IDENT_CHAR


defineI_SWITCHBOARD_GETVERSION


defineI_SWITCHBOARD_GETINFO


defineI_SWITCHBOARD_SETATTR

Sets the switchboard attributes. This IOCTL call is used for configuring connections on the switch board.

#include <sos/dev/switchboard.h>
#include <fcntl.h>
#include <unistd.h>

int uart_fd = open("/dev/uart0", O_RDWR);
ioctl(uart_fd, I_UART_SETATTR); //set default attributes

//now configure the UART in loopback mode
int fd = open("/dev/switchboard", O_RDWR);
switchboard_attr_t attr;
strcpy(attr.input_terminal, "uart0");
strcpy(attr.output_terminal, "uart0");
attr.o_flags = SWITCHBOARD_FLAG_CONNECT |
 SWITCHBOARD_FLAG_IS_PERSISTENT;
ioctl(fd, I_SWITCHBOARD_SETATTR, &attr); //uart0 is in loopback mode
close(fd); //connection persists until disconnected

defineI_SWITCHBOARD_SETACTION


defineI_SWITCHBOARD_TOTAL


enumswitchboard_flag_t

  • SWITCHBOARD_FLAG_CONNECT Configure a switchboard connection (used in o_flags of switchboard_attr_t)
  • SWITCHBOARD_FLAG_DISCONNECT Clears the specified connection (used in o_flags of switchboard_attr_t)
  • SWITCHBOARD_FLAG_IS_PERSISTENT Set to configure a persistent connection (used in o_flags of switchboard_attr_t)
  • SWITCHBOARD_FLAG_IS_CONNECTED Used in o_flags of switchboard_connection_t for status
  • SWITCHBOARD_FLAG_IS_READING_ASYNC Used in o_flags of switchboard_connection_t for status
  • SWITCHBOARD_FLAG_IS_WRITING_ASYNC Used in o_flags of switchboard_connection_t for status
  • SWITCHBOARD_FLAG_IS_ERROR The connection has stopped because of an error (nbyte has the error code)
  • SWITCHBOARD_FLAG_SET_TRANSACTION_LIMIT Use with SWITCHBOARD_FLAG_CONNECT to specify a transaction limit other than the default
  • SWITCHBOARD_FLAG_IS_FILL_ZERO If no data is available on a non-blocking input, a packet full of zeros is sent to the output
  • SWITCHBOARD_FLAG_IS_INPUT_NON_BLOCKING The connection input terminal should operate in non-blocking mode (return immediately if no data is available)
  • SWITCHBOARD_FLAG_IS_OUTPUT_NON_BLOCKING The connection output terminal should operate in non-blocking mode (return immediately if no data is available)
  • SWITCHBOARD_FLAG_IS_DESTROYED The connection has been destroyed (this flag is self clearing)
  • SWITCHBOARD_FLAG_IS_FILL_LAST_8 If no data is available on a non-blocking input, a packet is filled with the last byte of the previous packet
  • SWITCHBOARD_FLAG_IS_FILL_LAST_16 If no data is available on a non-blocking input, a packet is filled with the last 16-bit word of the previous packet
  • SWITCHBOARD_FLAG_IS_FILL_LAST_32 If no data is available on a non-blocking input, a packet is filled with the last 32-bit word of the previous packet
  • SWITCHBOARD_FLAG_IS_FILL_LAST_64 If no data is available on a non-blocking input, a packet is filled with the last 64-bit word of the previous packet
  • SWITCHBOARD_FLAG_CLEAN Cleanup connectections that have stopped on an error
  • SWITCHBOARD_FLAG_IS_CANCELED Set if a connection operation was cancelled


date: “2019-06-27” layout: post title: struct::switchboard_info_t katex: true

categories: struct

Methods

Details

public u32o_flags

Bitmask of supported flags


public u16connection_count

The total number of connections available


public u16connection_buffer_size

The internal buffer size (max number of bytes for persistent connections)


public u32transaction_limit

The maximum number of synchronous transactions that are allowed before the connection is aborted


public u32resd



date: “2019-06-27” layout: post title: struct::switchboard_terminal_t katex: true

categories: struct

Contains the data for a switchboard terminal.

Methods

Details

public charname

The name of the terminal


public u32loc

The location of the terminal (block location or channel depending on the device)


public u32bytes_transferred

Number of bytes transferred on the terminal


public s8priority

Hardware interrupt priority elevation


public u8device_type

Block or character device


public s16resd



date: “2019-06-27” layout: post title: struct::switchboard_connection_t katex: true

categories: struct

A switchboard connection defines input and output terminals as well as the number of bytes to transfer.

See also: switchboard_status_t

Methods

Details

public u32o_flags

Bitmask flags for connection state


public u16id

Connection id of total


public u16transaction_limit

The maximum number of synchronous transactions that can occur before aborting


publicswitchboard_terminal_tinput

Input device (device that is read)


publicswitchboard_terminal_toutput

Output device (device that is written)


public s32nbyte

Number of bytes to transfer (packet size for persisent connections); will be negative when reading to indicate an error


X

Thanks for Coming!

Subscribe to news and updates