Driver

The HDMI IP requires a processor to setup the core. This can be any processor. A HDMI driver (prt_hdmi_drv) is provided for this task. It is plain C with no operating system or vendor library behind it, so it ports to whatever core sits next to the IP.

Each IP-core carries its own system controller, and that controller runs the firmware for the HDMI protocol itself: hot plug detect, EDID, SCDC, the link and the PHY. This is what makes the core autonomous, and it is the main reason for having it. The protocol keeps running on the system controller's own timers and interrupts, so the application processor is free of the low level HDMI work. It decides what it wants, such as starting video at a given resolution, and hears what came of it through the callbacks.

The application processor loads that firmware into the system controller at start up, and from then on the two communicate through a mailbox, exchanging the tokens defined in prt_hdmi_tokens.h. Most API functions are such an exchange: they send a token to the system controller and wait for its answer. For the same reason a few are asynchronous: prt_hdmi_sta returns right away and its values arrive a moment later, in the status callback.

One prt_hdmi_ds_struct describes one IP-core, so either the transmitter or the receiver. A design with both keeps two of them and passes the right one to every call, which is also how the API is split: shared functions, transmitter functions and receiver functions.

The IP-core raises an interrupt when the system controller has sent mail. prt_hdmi_irq_handler belongs in that interrupt; it only reads the message and raises an event flag. The application calls prt_hdmi_evt_handler from its main loop and that is what dispatches the callbacks. Because of this split a callback runs in thread context: it may take its time and call the other API functions, which an interrupt handler could not.

An IP-core is brought up in this order. The reference design in prt_hdmi_app.c shows it in full.

prt_hdmi_set_base (&hdmitx, HDMITX_BASE_ADDR);   // find the IP-core
                                                 // hook prt_hdmi_irq_handler to its interrupt
prt_hdmi_rom_init (&hdmitx, rom_len, rom);       // load the system controller firmware
prt_hdmi_ram_init (&hdmitx, ram_len, ram);
prt_hdmi_init     (&hdmitx, PRT_HDMITX_ID);

prt_hdmi_set_cb   (&hdmitx, PRT_HDMI_CB_HPD, &hdmitx_hpd_cb);
prt_hdmi_set_cb   (&hdmitx, PRT_HDMI_CB_LNK, &hdmi_lnk_cb);
/* ... the other callbacks ... */

while (1)
    prt_hdmi_evt_handler (&hdmitx);              // dispatches the callbacks

API

This section provides information about the driver API. The functions are grouped the same way as in prt_hdmi_drv.h: shared functions that apply to both IP-cores, followed by the transmitter and receiver functions.

Shared

Transmitter

Receiver

Callbacks

The callback functions are used by the driver to signal the application about an event. Functions are registered using the prt_hdmi_set_cb function. The driver raises an event flag when the system controller reports something, and prt_hdmi_evt_handler dispatches the handlers from thread context, so a handler may take its time and use the other API functions. The handler names below are the ones used in the reference design. The diagram shows the HDMI states and the callbacks that follow from them; the status and debug callbacks are not part of that flow.

Figure 1: HDMI callbacks