uart_tt_virt.h

Go to the documentation of this file.

/*
 * Copyright (c) 2024 Tenstorrent AI ULC
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef TENSTORRENT_UART_TT_VIRT_H_
#define TENSTORRENT_UART_TT_VIRT_H_
 
#include <assert.h>
#include <stdatomic.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#ifdef CONFIG_UART_TT_VIRT_TX_BLOCK
#include <zephyr/kernel.h>
#endif
 
#ifdef __cplusplus
extern "C" {
#endif


enum tt_vuart_role {
        TT_VUART_ROLE_DEVICE, 
        TT_VUART_ROLE_HOST,   
};

struct tt_vuart {
        uint32_t magic;    
        uint32_t rx_cap;   
        uint32_t rx_head;  
        uint32_t rx_tail;  
        uint32_t tx_cap;   
        uint32_t tx_head;  
        uint32_t tx_oflow; 
        uint32_t tx_tail;  
        uint32_t version;  
        uint8_t buf[];     
};

static inline size_t tt_vuart_inst(volatile const struct tt_vuart *vuart)
{
        return vuart->version >> 24;
}

static inline uint32_t tt_vuart_buf_size(uint32_t head, uint32_t tail)
{
        return tail - head;
}

static inline uint32_t tt_vuart_buf_space(uint32_t head, uint32_t tail, uint32_t cap)
{
        return cap - (tt_vuart_buf_size(head, tail));
}

static inline bool tt_vuart_buf_empty(uint32_t head, uint32_t tail)
{
        return tt_vuart_buf_size(head, tail) == 0;
}

static inline bool tt_vuart_buf_full(uint32_t head, uint32_t tail, uint32_t cap)
{
        return tt_vuart_buf_size(head, tail) == cap;
}

static inline int tt_vuart_poll_in(volatile struct tt_vuart *vuart, unsigned char *p_char,
                                   enum tt_vuart_role role)
{
        uint32_t cap;
        uint32_t offs;
        uint32_t tail;
        uint32_t head;
        volatile atomic_uint *headp;
 
        do {
                if (role == TT_VUART_ROLE_DEVICE) {
                        headp = (volatile atomic_uint *)&vuart->rx_head;
                        head = vuart->rx_head;
                        tail = vuart->rx_tail;
                        cap = vuart->rx_cap;
                        offs = vuart->tx_cap;
                } else if (role == TT_VUART_ROLE_HOST) {
                        headp = (volatile atomic_uint *)&vuart->tx_head;
                        head = vuart->tx_head;
                        tail = vuart->tx_tail;
                        cap = vuart->tx_cap;
                        offs = 0;
                } else {
                        assert((role == TT_VUART_ROLE_DEVICE) || (role == TT_VUART_ROLE_HOST));
                        return -1;
                }
 
                if (tt_vuart_buf_empty(head, tail)) {
                        return -1;
                }
 
                /*
                 * Read before publishing the advanced head. Otherwise a producer can
                 * observe the freed slot and overwrite it before it is consumed.
                 */
                atomic_thread_fence(memory_order_acquire);
                unsigned char ch = vuart->buf[offs + (head % cap)];
 
                if (atomic_compare_exchange_strong(headp, &head, head + 1)) {
                        *p_char = ch;
                        return *p_char;
                }
        } while (true);
 
        assert(false);
        return -1;
}

static inline void tt_vuart_poll_out(volatile struct tt_vuart *vuart, unsigned char out_char,
                                     enum tt_vuart_role role)
{
        uint32_t head;
        uint32_t cap;
        uint32_t offs;
        uint32_t tail;
        volatile atomic_uint *tailp;
 
#ifdef CONFIG_UART_TT_VIRT_TX_BLOCK
        const uint32_t tx_block_deadline =
                k_uptime_get_32() + CONFIG_UART_TT_VIRT_TX_BLOCK_TIMEOUT_MS;
#endif
 
        do {
                if (role == TT_VUART_ROLE_DEVICE) {
                        tailp = (volatile atomic_uint *)&vuart->tx_tail;
                        tail = vuart->tx_tail;
                        head = vuart->tx_head;
                        cap = vuart->tx_cap;
                        offs = 0;
                } else if (role == TT_VUART_ROLE_HOST) {
                        tailp = (volatile atomic_uint *)&vuart->rx_tail;
                        tail = vuart->rx_tail;
                        head = vuart->rx_head;
                        cap = vuart->rx_cap;
                        offs = vuart->tx_cap;
                } else {
                        assert((role == TT_VUART_ROLE_DEVICE) || (role == TT_VUART_ROLE_HOST));
                        break;
                }
 
                if ((role == TT_VUART_ROLE_DEVICE) && tt_vuart_buf_full(head, tail, cap)) {
#ifdef CONFIG_UART_TT_VIRT_TX_BLOCK
                        if ((int32_t)(k_uptime_get_32() - tx_block_deadline) >= 0) {
                                ++vuart->tx_oflow;
                                return;
                        }
                        continue;
#else
                        ++vuart->tx_oflow;
                        return;
#endif
                }
 
                /*
                 * Store the byte before publishing the new tail, so a consumer that
                 * observes the tail also observes the data.
                 */
                vuart->buf[offs + (tail % cap)] = out_char;
                atomic_store_explicit(tailp, tail + 1, memory_order_release);
                return;
        } while (true);
}
 
#ifdef __ZEPHYR__
#include <zephyr/device.h>

volatile struct tt_vuart *uart_tt_virt_get(const struct device *dev);

volatile struct tt_vuart *uart_tt_virt_lookup_callback(size_t inst);

void uart_tt_virt_init_callback(const struct device *dev, size_t inst);
 
#endif

 
#ifdef __cplusplus
}
#endif
 
#endif /* TENSTORRENT_UART_TT_VIRT_H_ */