Unclear logic behind pl011_tx_chars() in amba-pl011 Linux kernel module

Question

I'm trying to understand how Linux driver for AMBA serial port (amba-pl011.c) sends characters in non-DMA mode. For port operations, this driver registers only following callbacks:

static struct uart_ops amba_pl011_pops = {
    .tx_empty       = pl011_tx_empty,
    .set_mctrl      = pl011_set_mctrl,
    .get_mctrl      = pl011_get_mctrl,
    .stop_tx        = pl011_stop_tx,
    .start_tx       = pl011_start_tx,
    .stop_rx        = pl011_stop_rx,
    .enable_ms      = pl011_enable_ms,
    .break_ctl      = pl011_break_ctl,
    .startup        = pl011_startup,
    .shutdown       = pl011_shutdown,
    .flush_buffer   = pl011_dma_flush_buffer,
    .set_termios    = pl011_set_termios,
    .type           = pl011_type,
    .release_port   = pl011_release_port,
    .request_port   = pl011_request_port,
    .config_port    = pl011_config_port,
    .verify_port    = pl011_verify_port,
    .poll_init     = pl011_hwinit,
    .poll_get_char = pl011_get_poll_char,
    .poll_put_char = pl011_put_poll_char };

As you can see, there's no character sending operation among them, namely, pl011_tx_chars() function is not listed there. Since pl011_tx_chars() is declared static, it is not exposed outside the module. I found that within the module it is called only from pl011_int() function which is an interrupt handler. It is called whenever UART011_TXIS occurs:

if (status & UART011_TXIS) pl011_tx_chars(uap);

The function pl011_tx_chars() itself writes characters from circular buffer to UART01x_DR port until the fifo queue size is reached (function returns then so more data will be written at the next interrupt) or until circular buffer is empty (pl011_stop_tx() is called then). As we can see, pl011_start_tx() and pl011_stop_tx() are listed in AMBA port operations (so they can be called as callbacks despite their local static declaration). Seems reasonable, thing is, these two function do something very simple:

static void pl011_stop_tx(struct uart_port *port)
{
        struct uart_amba_port *uap = (struct uart_amba_port *)port;

        uap->im &= ~UART011_TXIM;
        writew(uap->im, uap->port.membase + UART011_IMSC);
        pl011_dma_tx_stop(uap);
}

static void pl011_start_tx(struct uart_port *port)
{
        struct uart_amba_port *uap = (struct uart_amba_port *)port;

        if (!pl011_dma_tx_start(uap)) {
                uap->im |= UART011_TXIM;
                writew(uap->im, uap->port.membase + UART011_IMSC);
        }
}

Since I don't have CONFIG_DMA_ENGINE set, pl011_dma_tx_start() and pl011_dma_tx_stop() are just stubs:

static inline void pl011_dma_tx_stop(struct uart_amba_port *uap)
{
}

static inline bool pl011_dma_tx_start(struct uart_amba_port *uap)
{
        return false;
}

Seems like the only thing that pl011_start_tx() does is to arm UART011_TXIM interrupt while the only thing that pl011_stop_tx() does is to disarm it. Nothing initiates the transmission!

I looked at serial_core.c - it's the only file where start_tx operation is invoked, in four places (by the registered callback). The most promissing place is uart_write() function. It fills circular buffer with data and calls local static uart_start() function which is very simple:

static void __uart_start(struct tty_struct *tty)
{
        struct uart_state *state = tty->driver_data;
        struct uart_port *port = state->uart_port;

        if (!uart_circ_empty(&state->xmit) && state->xmit.buf &&
            !tty->stopped && !tty->hw_stopped)
                port->ops->start_tx(port);
}

static void uart_start(struct tty_struct *tty)
{
        struct uart_state *state = tty->driver_data;
        struct uart_port *port = state->uart_port;
        unsigned long flags;

        spin_lock_irqsave(&port->lock, flags);
        __uart_start(tty);
        spin_unlock_irqrestore(&port->lock, flags);
}

As you can see, no one sends initial characters to the UART port, circular buffer is filled and everything is waiting for UART011_TXIS interrupt. Is it possible that arming UART011_TXIM interrupt instantly emits UART011_TXIS? I looked into DDI0183.pdf (PrimeCell® UART (PL011) Technical Referecne Manual), Chapter 3: Programmers Model, section 3.4: Interrupts, subsection 3.4.3 UARTTXINTR. What it says is:

....

The transmit interrupt changes state when one of the following events occurs:

• If the FIFOs are enabled and the transmit FIFO reaches the programmed trigger level. When this happens, the transmit interrupt is asserted HIGH. The transmit interrupt is cleared by writing data to the transmit FIFO until it becomes greater than the trigger level, or by clearing the interrupt.

• If the FIFOs are disabled (have a depth of one location) and there is no data present in the transmitters single location, the transmit interrupt is asserted HIGH. It is cleared by performing a single write to the transmit FIFO, or by clearing the interrupt.

....

The note below is even more interesting:

.... The transmit interrupt is based on a transition through a level, rather than on the level itself. When the interrupt and the UART is enabled before any data is written to the transmit FIFO the interrupt is not set. The interrupt is only set once written data leaves the single location of the transmit FIFO and it becomes empty. ....

The emphasis above is mine. I don't know if my English is not sufficient, but from the words above I can't find where it states that unlocking transmit interrupt can be used for triggering transmit routine. What am I missing?

Answer 1

The ARM docs say that the PL011 is a "16550-ish" UART. This sort of gets them off the hook for fully specifying its behavior and instead sends you to the 16550 docs, which state in the "FIFO interrupt mode operation" section...

When the XMIT FIFO and transmitter interrupts are enabled (FCR0e1, IER1e1), XMIT interrupts will occur as follows: A. The transmitter holding register interrupt (02) occurs when the XMIT FIFO is empty; it is cleared as soon as the transmitter holding register is written to (1 to 16 characters may be written to the XMIT FIFO while servicing this interrupt) or the IIR is read.

So, it appears that if the FIFO and TX holding register are empty and you enable TX interrupts, you should immediately see a TX interrupt that kickstarts the sending process and fills the holding register and then the FIFO. Once those drain back down below the FIFO trigger, then another interrupt will be generated to keep the process going for as long as there is more buffered data to be sent.