How do these uart structs as function parameters work?

Question

I have this code I'm trying to understand but I'm stuck, so maybe one of you good people could point me in the right direction.

Taking it step by step I have this part of an initialisation...

volatile struct UART *pTXD1;
volatile struct UARTINIT *pPort1;

...the strcuts...

struct UARTINIT
{
    union SR_BYTE SR; /* Status register */
    BYTE DR; /* Data register */
    BYTE BRR1; /* Baud Rate reg 1 */
    BYTE BRR2; /* Baud Rate reg 2 */
    union CR1_BYTE CR1; /* Control register 1 */
    union CR2_BYTE CR2; /* Control register 2 */
    BYTE CR3; /* Control register 3 */
    BYTE CR4; /* Control register 4 */
};

struct UART
{
    BYTE *Buffer;
    WORD max;
    WORD read;
    WORD write;
    BYTE Baud;
    BYTE stopp;
};

...function call...

Transmit_Uart(pTXD1, pPort1);

...the function

void Transmit_Uart(struct UART *Buff, struct UARTINIT *USART)
{
    if ((*Buff).write != (*Buff).read)
    {
        if ((*USART).SR.bit.TC)
        {
            (*Buff).read = ((*Buff).read + 1) % (*Buff).max;
            (*USART).DR = (*Buff).Buffer[(*Buff).read];
        }
    }
    else
        (*Buff).stopp = OFF;
    return;
}

My problem is that I don't understand what information is written into the structs. The function is called with pTXD1 and pPort1 as parameters, but those two are just pointers to structs, are they not?

I apologize if my question is not understandable, and will gladly provide further information as needed.

Answer 1

They use the struct UARTINIT as a way to visualize memory-mapped hardware registers in the UART hardware. The struct must correspond exactly to the register layout for this to work, so whoever wrote the code must ensure that no struct padding is active. (Generally not an issue on 8 or 16 bit MCUs, but will be on bigger cores.)

So the struct pointer pPort1 will point at the first register in one of potentially several UART hardwares on the chip. The registers are already "allocated" - they exist is the form of memory-mapped hardware.

The UART struct seems to simply be a user-defined struct used for storing various settings and for shovelling data in and out of the UART hardware buffers. If so, this struct must be allocated somewhere in user RAM. Or possibly it is also a register memory map, in which case you have some very strange hardware.

Some manner of documentation is needed to understand how its used. Code such as ((*Buff).read + 1) % (*Buff).max; looks quite obscure; I have no idea why they aren't simply letting the driver read/write raw data bytes.