{"id":94,"date":"2023-08-10T22:45:30","date_gmt":"2023-08-11T02:45:30","guid":{"rendered":"https:\/\/www.vociferousvoid.org\/?p=94"},"modified":"2023-08-11T07:29:16","modified_gmt":"2023-08-11T11:29:16","slug":"uart-what-you-read","status":"publish","type":"post","link":"https:\/\/www.vociferousvoid.org\/index.php\/2023\/08\/10\/uart-what-you-read\/","title":{"rendered":"UART What You Read"},"content":{"rendered":"\n<p>Computers are not much use unless you can interact with them. This means that the user must be able to input data into the system&#8217;s memory, and that data can be retrieved and displayed (or output) for the user. The most common way to interact with computers (i.e. smartphones) is via a touch screen which provides both the input and output modality. However, this is a complex mechanism for communicating with the user that requires a non-trivial software stack (i.e. layers of different software which handle the details of drawing on the screen and recognizing touch input).<\/p>\n\n\n\n<p>A more basic form of input and output can be carried out via the device&#8217;s serial port. As the name implies, when using this mechanism, data is exchanged one byte at a time serially. The most common type of serial controller is the Universal Asynchronous Receiver\/Transmitter (UART). The UART controller is not an intrinsic part of the CPU core, however, it is a peripheral device with its own specification. The CPU will access the serial controller using memory-mapped addresses.<\/p>\n\n\n\n<p>Memory-mapped addresses are setup when the chip is designed. A particular range of physical addresses are reserved to access peripherals such as serial controllers. Individual addresses will map to registers in the peripheral device. Since the addresses used to exchange data with the UART controller may vary from one machine to another, the software used to carry out input and output via the UART controller will be specific to a particular chip.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">History of the UART<\/h2>\n\n\n\n<p>Serial communication was introduced with the INS8250 UART device in the IBM PC\/XT computer<sup><a id=\"fnr.1\" class=\"footref\" href=\"#fn.1\">1<\/a><\/sup>. The INS8250 uses eight I\/O ports with a one-byte send buffer, and a one-byte receive buffer. This device was upgraded in the AT series to the NS16450 device which improves the design of the INS8250 allowing it to be used with faster bus speeds. the NS16450 series is capable of handling communication speeds of up to 38.4 KB\/s.<\/p>\n\n\n\n<p>To respond to the demands for even higher data rates, a new series of UART devices was developed: the 16550A<sup><a id=\"fnr.1.100\" class=\"footref\" href=\"#fn.1\">1<\/a><\/sup> which makes use of two 16-bit FIFO buffers to queue input and output data. This device allows for serial communication speeds of up to 115.2 KB\/s. This device and its successors have become the most popular UART design and is the device emulated by the QEMU virt machine.<\/p>\n\n\n\n<p>The RISC-V virtual machine defined by the QEMU emulator uses the address range <code>0x10000000<\/code>&#8211;<code>0x10000100<\/code> to access the UART controller. Specific addresses in this range map to the controller&#8217;s registers. A program may read and write byte values to the registers using these addresses.<\/p>\n\n\n\n<p>Although the address range mapped to UART I\/O ports spans 256 bytes (<code>0x100<\/code>), only eight bytes are needed to access the controller&#8217;s registers. This implies that there can be as many as 16 serial I\/O devices available on the given machine; however, only one UART is actually used. The relevant registers are described in table 1<sup><a id=\"fnr.2\" class=\"footref\" href=\"#fn.2\">2<\/a><\/sup>:<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table><thead><tr><th scope=\"col\">Register<\/th><th scope=\"col\">Offset<\/th><th scope=\"col\">Direction<\/th><th scope=\"col\">Purpose<\/th><\/tr><\/thead><tbody><tr><td>RBR<\/td><td>0<\/td><td>Read-Only<\/td><td>receive buffer<\/td><\/tr><tr><td>THR<\/td><td>0<\/td><td>Write-Only<\/td><td>transmit holding<\/td><\/tr><tr><td>DLL<\/td><td>0<\/td><td>Read\/Write<\/td><td>Divisor Latch LSB<\/td><\/tr><tr><td>DLH<\/td><td>0<\/td><td>Read\/Write<\/td><td>Divisor Latch MSB<\/td><\/tr><tr><td>IER<\/td><td>1<\/td><td>Read\/Write<\/td><td>interrupt enable<\/td><\/tr><tr><td>IIR<\/td><td>2<\/td><td>Read-Only<\/td><td>interrupt identification<\/td><\/tr><tr><td>FCR<\/td><td>2<\/td><td>Write-Only<\/td><td>FIFO control<\/td><\/tr><tr><td>LCR<\/td><td>3<\/td><td>Read\/Write<\/td><td>Line control<\/td><\/tr><tr><td>MCR<\/td><td>4<\/td><td>Read\/Write<\/td><td>modem control<\/td><\/tr><tr><td>LSR<\/td><td>5<\/td><td>Read-Only<\/td><td>line status<\/td><\/tr><tr><td>MSR<\/td><td>6<\/td><td>Read-Only<\/td><td>modem status<\/td><\/tr><tr><td>SCR<\/td><td>7<\/td><td>Read\/Write<\/td><td>scratch<\/td><\/tr><\/tbody><\/table><figcaption class=\"wp-element-caption\">Table 1: 16550A UART registers<\/figcaption><\/figure>\n\n\n\n<p>Note that several of the registers map to the same offset in memory. This is possible because some of them are read-only while others are write-only. Therefore the offsets are re-used; the mapping will change based on the value of the line control register (<code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-31\">LCR<\/a><\/code>) at offset 3. If bit 7 of the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-31\">LCR<\/a><\/code> register is asserted, the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-10\">THR<\/a><\/code> (transmit holding), <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-11\">RBR<\/a><\/code> (receive buffer), and <code>IER<\/code> (interrupt enable) registers are disabled; reads and writes to these offset will be redirected to the <code>DLL<\/code> (divisor latch LSB) and <code>DLH<\/code> (divisor latch MSB) which are used to set the baud rate.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Output<\/h2>\n\n\n\n<p>The assembly function to write a single byte to the serial controller is illustrated in the following listing:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>__uart_putc:\n\tfunction_prologue 0\n1:\tlbu\tt0, LSR(a0)\t# Get the line status\n\tandi\tt0, t0, LSR_RE  # Mask all but the status bit\n\tbeqz\tt0, 1b          # Loop until THR is ready\n\tsb\ta1, THR(a0)     # Write character\n\tfunction_epilogue 0\n\tret<\/code><\/pre>\n\n\n\n<p>The inputs of this function are the base address of the UART controller (in register <code>a0<\/code>), and the byte to write the the device (in register <code>a1<\/code>).<\/p>\n\n\n\n<p>This code assumes that bit 7 of the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-31\">LCR<\/a><\/code> register is clear (i.e. 0). The function uses two constants corresponding with the offsets of the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-10\">THR<\/a><\/code> and <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-36\">LSR<\/a><\/code> registers (offset 0 and 5 respectively). Moreover, the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-38\">LSR_RE<\/a><\/code> constant represents a bit mask (0x20) to isolate bit 5 of the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-36\">LSR<\/a><\/code> status register. If this bit is asserted, then the transmit holding register is ready to receive a byte of data.<\/p>\n\n\n\n<p>The <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/8612d0486ae94ce6cd67f8152b6157585f9c4742\/shared\/uart.S#lines-53\">__uart_putc<\/a><\/code> function first checks the line status register to determine if the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-10\">THR<\/a><\/code> register is ready to receive data. This check is performed by verifying bit 5 of the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-36\">LSR<\/a><\/code> status register (using the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-38\">LSR_RE<\/a><\/code> constant). If this bit is asserted, the byte from register <code>a1<\/code> is stored at offset <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-10\">THR<\/a><\/code> from the base address stored in register <code>a0<\/code>. Otherwise, the function loops to verify the line status register again.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Input<\/h2>\n\n\n\n<p>The assembly code to read a single byte from the UART controller is illustrated in the following listing:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>__uart_getc:\n        li      a1, -1\n        lbu     t0, LSR(a0)     # Get the line status (get LSR)\n        andi    t0, t0, LSR_DA\n        beqz    t0, .L__uart_getc_exit\n        lbu     a1, RBR(a0)\n.L__uart_getc_exit:\n        ret<\/code><\/pre>\n\n\n\n<p>Much like the output function, the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/shared\/uart.S#lines-101\">__uart_getc<\/a><\/code> function takes the base address of the UART controller in register <code>a0<\/code>. The character code is returned in register <code>a1<\/code>.<\/p>\n\n\n\n<p>The <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-36\">LSR<\/a><\/code> register is queried to determine whether or not there is unread data available in the receive buffer (offset <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-11\">RBR<\/a><\/code>). If bit 0 is asserted (masked using the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-37\">LSR_DA<\/a><\/code>) the function loads the contents of the read buffer into register <code>a1<\/code>. Unlike the input function, the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/shared\/uart.S#lines-101\">__uart_getc<\/a><\/code> function does not loop until data arrives. If no unread data is available in the receive buffer, the function simply returns -1.<\/p>\n\n\n\n<p>On a successful read, the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-37\">LSR_DA<\/a><\/code> bit of the line-status register is automatically cleared. It is asserted again once new data becomes available for reading. The mechanism by which this is carried out is an implementation detail of the controller. However, the upshot of this is that it&#8217;s fairly easy to determine if there is new data available for reading in the UART&#8217;s receive queue.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Can I Finish?<\/h3>\n\n\n\n<p>The function for reading from the serial device polls the line status register to determine when unread data is available. Even though a program may have well defined points in its execution where input is required, the arrival of the input will nonetheless be asynchronous. The program may call the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/shared\/uart.S#lines-101\">__uart_getc<\/a><\/code> function in a loop until all of the required data is received. However, this prevents the processor from being used to carry out other computations while waiting for user input.<\/p>\n\n\n\n<p>To work around this, the UART controller can be configured to trigger an interrupt whenever there is new data available for reading via the <code><a href=\"https:\/\/bitbucket.org\/marc_perron\/risc-v\/src\/mainline\/include\/virt\/uart.h#lines-15\">IER<\/a><\/code> register (interrupt enable). The read can be carried out by an interrupt handler. This allows processing to continue until new data arrives. At which point execution will trap to the function to carry out the read.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">In Summary<\/h2>\n\n\n\n<p>The NS16550A UART controller is a basic mechanism to support I\/O. Data is read and\/or written to the serial ports one byte at a time and transmitted to the opposite end. This provides a simple mechanism for programs to exchange data with their users. The serial ports are mapped to specific addresses in the system&#8217;s main memory. Reads and\/or writes to those addresses allow programs to interact with the controller as a peripheral device.<\/p>\n\n\n\n<p>Output is the simpler case from the program&#8217;s perspective when using the UART since this action is effectively synchronous; the program knows when output is needed.<\/p>\n\n\n\n<p>Input, is inherently asynchronous; it is not possible to predict when the user will provide input. Polling the line status register will prevent the CPU from doing other useful work.<\/p>\n\n\n\n<p>Although the UART controller can be configured to trigger an interrupt when the line status changes, this is beyond the scope of the current article. Handling interrupts is complex enough that the subject should be treated on its own. In the meantime, the poll design pattern is good enough to get an idea of how to interact with the UART controller and other on-chip peripherals in general (via memory mapped addresses).<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Footnotes<\/h2>\n\n\n\n<p><sup><a id=\"fn.1\" class=\"footnum\" href=\"#fnr.1\">1<\/a><\/sup>\n<a href=\"https:\/\/www.freebsd.org\/doc\/en_US.ISO8859-1\/articles\/serial-uart\/index.html\">https:\/\/www.freebsd.org\/doc\/en_US.ISO8859-1\/articles\/serial-uart\/index.html<\/a><\/p>\n\n\n\n<p><sup><a href=\"https:\/\/www.vociferousvoid.org\/wp-admin\/post.php?post=94&amp;action=edit#fnr.2\">2<\/a><\/sup> <a href=\"https:\/\/www.lammertbies.nl\/comm\/info\/serial-uart\">https:\/\/www.lammertbies.nl\/comm\/info\/serial-uart<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Computers are not much use unless you can interact with them. This means that the user must be able to input data into the system&#8217;s memory, and that data can be retrieved and displayed (or output) for the user. The most common way to interact with computers (i.e. smartphones) is via a touch screen which [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[4],"tags":[],"class_list":["post-94","post","type-post","status-publish","format-standard","hentry","category-risc-v"],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/www.vociferousvoid.org\/index.php\/wp-json\/wp\/v2\/posts\/94","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.vociferousvoid.org\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.vociferousvoid.org\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.vociferousvoid.org\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.vociferousvoid.org\/index.php\/wp-json\/wp\/v2\/comments?post=94"}],"version-history":[{"count":10,"href":"https:\/\/www.vociferousvoid.org\/index.php\/wp-json\/wp\/v2\/posts\/94\/revisions"}],"predecessor-version":[{"id":105,"href":"https:\/\/www.vociferousvoid.org\/index.php\/wp-json\/wp\/v2\/posts\/94\/revisions\/105"}],"wp:attachment":[{"href":"https:\/\/www.vociferousvoid.org\/index.php\/wp-json\/wp\/v2\/media?parent=94"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.vociferousvoid.org\/index.php\/wp-json\/wp\/v2\/categories?post=94"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.vociferousvoid.org\/index.php\/wp-json\/wp\/v2\/tags?post=94"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}