A C++ template library for embedded applications
Designed and maintained by
Aster Consulting Ltd
Join the ETL community

io_port

A set of templates for building interface classes to memory mapped hardware ports.
They avoid the need to directly map carefully packed (and possibly non-portable) structures onto memory addresses.

Note: A read from a write-only,  or write to a read-only port will result in a compile time error.

Defines classes for the following IO types:-
Read / Write.
Read only.
Write only.
Write only with shadow register.

With a shadow register, the value written is stored locally and may be read back.

The port may either have an address fixed at compile time or set at runtime. The compile time versions require no extra
overhead compared to a plain memory mapped structure.

Ports may be sent as parameters to algorithms that expect iterators, except the runtime address version of
io_port_wos, which must use the built-in iterator if the shadow value is to be correctly updated for writes.

All classes define the following typedefs.

typedef volatile T*       pointer;
typedef volatile const T* const_pointer;
typedef volatile T&       reference;
typedef volatile const T& const_reference;

Compile time port addresses

io_port_rw

Read/write port.
Forward iterator.

io_port_rw<typename T, uintptr_t ADDRESS>


operator T() const
Read the value. Conversion operator to T.

T read() const
Read the value.

void write(T value_)
Write the value.

io_port_rw& operator =(T value_)
Write the value.

reference operator *()
const_reference operator *() const
Returns a reference to the port.

io_port_rw& operator ++()
io_port_rw operator ++(int)
Does nothing. For iterator compatibility.

pointer get_address()
const_pointer get_address() const
Gets the address of the port.

io_port_ro

Read only port.
Input iterator.

io_port_ro<typename T, uintptr_t ADDRESS>

operator T() const
Read the value. Conversion operator to T.

T read() const
Read the value.

const_reference operator *() const
Returns a reference to the port.

io_port_ro& operator ++()
io_port_ro operator ++(int)
Does nothing. For iterator compatibility.

pointer get_address()
const_pointer get_address() const
Gets the address of the port.

io_port_wo

Write only port.
Output iterator.

io_port_wo<typename T, uintptr_t ADDRESS>

void operator =(T value)
Write the value.

void write(T value_)
Write the value.

io_port_wo& operator *()
Returns a reference to the port.

io_port_wo& operator ++()
io_port_wo operator ++(int)
Does nothing. For iterator compatibility.

pointer get_address()
const_pointer get_address() const
Gets the address of the port.

io_port_wos

Write only port with shadow register for reading.
Forward iterator.

io_port_wos<typename T, uintptr_t ADDRESS>

operator T() const
Read the shadow value.

T read() const
Read the shadow value.

void write(T value_)
Write the value to the port and the shadow value.

io_port_wos& operator =(T value_)
io_port_wos& operator *()
Returns a reference to the port.

const_reference operator *() const
Returns a reference to the value.

io_port_wos& operator ++()
io_port_wos operator ++(int)
Does nothing. For iterator compatibility.

pointer get_address()
Gets the address of the port.

Example serial port

template <uintptr_t ADDRESS>
struct serial_port
{
  etl::io_port_ro<char,     ADDRESS>     rxdata;   // Read only rx data register.
  etl::io_port_wo<char,     ADDRESS + 1> txdata;   // Write only tx register.
  etl::io_port_rw<uint16_t, ADDRESS + 2> control;  // Read / write control register.
  etl::io_port_ro<uint16_t, ADDRESS + 4> status;   // Read only status register.
  etl::io_port_wos<uint8_t, ADDRESS + 6> control2; // Write only with shadow register.
};

serial_port<0x800> port; // A serial port at address 0x800

char data   = port.rxdata;
port.txdata = 'A';

data = port.txdata; // Compile error!

std::copy(txBuffer.begin(), txBuffer.end(), serial_port.txdata);

std::copy_n(serial_port.rxdata, serial_port.status, std::back_inserter(rxBuffer));

Runtime time port addresses

io_port_rw

Read/write port.
Forward iterator.

io_port_rw<typename T>


io_port_rw()
Default constructor.

io_port_rw(void* address)
Construct with a port address.

io_port_rw(const io_port_rw& other)
Copy constructor.

io_port_rw& operator =(const io_port_rw& other)
Assignment from another io_port_rw<T>

void set_address(uintptr_t address)
Sets the port address.

pointer get_address()
const_pointer get_address() const
Gets the address of the port.

operator T() const
Read the value.

T read() const
Read the value.

void write(T value)
Write the value.

io_port_rw& operator =(T value)
Write the value.

reference operator *()
const_reference operator *() const
Returns a reference to the value.

io_port_rw& operator ++()
io_port_rw operator ++(int)
Does nothing. For iterator compatibility.

io_port_ro

Read-only port.
Input iterator.

io_port_rw<typename T>

io_port_ro()
Default constructor.

io_port_ro(void* address)
Construct with a port address.

io_port_ro(const io_port_ro& other)
Copy constructor.

io_port_ro& operator =(const io_port_ro& other)
Assignment from another io_port_ro<T>

void set_address(void* address)
Sets the port address.

const_pointer get_address() const
Gets the address of the port.

operator T() const
Read the value.

T read() const
Read the value.

const_reference operator *() const
Returns a reference to the value.

io_port_ro& operator ++()
io_port_ro operator ++(int)
Does nothing. For iterator compatibility.

io_port_wo

Write-only port.
Output iterator.

io_port_wo<T>

io_port_wo()
Default constructor.

io_port_wo(void* address_)
Construct from port address.

io_port_wo(const io_port_wo& other_)
Copy constructor

io_port_wo& operator =(const io_port_wo& other_)
Read from another io_port_wo.

void set_address(void* address_)
Set the IO port address.

pointer get_address()
const_pointer get_address() const
Get the IO port address.

void write(T value_)
Write the value.

void operator =(T value)
Write the value.

io_port_wo& operator *()
Get a reference to the port.

io_port_wo& operator ++()
io_port_wo operator ++(int)
Does nothing. For iterator compatibility.

io_port_wos

Write-only port with shadow register.
Output iterator.

io_port_wos<T>

io_port_wos()
Default constructor.

io_port_wos(void* address_)
Construct from a port address.

io_port_wos(const io_port_wos& other_)
Copy constructor.

io_port_wos& operator =(const io_port_wos& other_)
Assign from another io_port_wos.

void set_address(void* address_)
Sets the port address.

pointer get_address()
const_pointer get_address() const
Gets the port address.

iterator get_iterator()
Gets a port iterator. This is necessary if the port is to be used in an STL style algorithm where the iterator is passed by
value.

operator T() const
Read the value.

T read() const
Read the value.

void write(T value_)
Write the value.

io_port_wos& operator =(T value_)
Write the value.

io_port_wos&  operator *()
Get a reference to the IO port.

const_reference operator *() const
Get a reference to the value.

io_port_wos& operator ++()
io_port_wos operator ++(int)
Does nothing. For iterator compatibility.

Example serial port


struct serial_port
{
  serial_port(uint8_t* base)
    : rxdata(base),
      txdata(base + 1),
      control(base + 2),
      status(base + 4),
      control2(base + 6)
  {
  }

  etl::io_port_ro<char>     rxdata;   // Read only rx data register.
  etl::io_port_wos<char>    txdata;   // Write only tx register with shadow register.
  etl::io_port_rw<uint16_t> control;  // Read / write control register.
  etl::io_port_ro<uint16_t> status;   // Read only status register.
  etl::io_port_wos<uint8_t> control2; // Write only with shadow register.
};

serial_port port(0x800);

char data   = port.rxdata;
port.txdata = 'A';

data = port.txdata; // Compile error!

// Tx data is a WOS, so use the iterator if we want to be able to read the last value written.
std::copy(txBuffer.begin(), txBuffer.end(), serial_port.txdata.get_iterator());

std::copy_n(serial_port.rxdata, serial_port.status, std::back_inserter(rxBuffer));
                                                  
io_port.h