util/docgen/examples/uart16550.hjson

{
  name: "UART16550",
  clock_primary: "clk_fixed",
  bus_device: "tlul",

  regwidth: 8,
  registers: [
    {name: "DATA", desc: "UART data",
      swaccess: "rw", fields: [
	  { bits: "7:0", resval: "x", desc: '''
             A read returns the **bold character** in the receive buffer if
             !!LCR.DLAB is clear, or the *italic low byte* of the ** bold
	     divisor split over line** if
	     !!LCR.DLAB is set.  Writes send characters to the
	     transmitter holding
             buffer if !!LCR.DLAB is clear, or set the low byte of the
             divisor if DLAB in !!LCR is set.
            '''
	  }
      ]
    },
    {name: "IER", desc: "Interrupt enable register", swaccess: "rw", fields: [
      {bits: "0", name: "RDAE", desc: '''
        Enable Received Data Available interrupt. If this bit is set
        an interrupt will be raised whenever the receive FIFO contains
        data. This reference is to a !!BOGUS register
	'''
      }
      {bits: "1", name: "TXEE", desc: '''
        Enable Transmit holding register empty interrupt. If this bit
        is set then an interrupt will be raised whenever the
        transmitter buffer is empty.
	'''
      }
      {bits: "2", name: "RLE", desc: '''
        Enable Receiver Line Status. If this bit is set then an
        interrupt will be raised whenever the receive side line status
        changes.
	'''
      }
      {bits: "3", name: "MSE", desc: '''
        Enable Modem Status interrupt. If this bit is set then an
        interrupt will be raised whenever the modem status changes.
	'''
      }
      {bits: "4", name: "SLP", desc: '''
        If this bit is set the UART will enter sleep mode. Operation
        will be stopped until a transition is detected on DIN, CTS_L,
        DSR_L, DCD_L or RI_L.
	'''
      }
      {bits: "5", name: "LPE", desc: '''
        If this bit is set the UART will enter low power mode, the
        same as sleep.
	'''
      }
    ]},
    {sameaddr: [
	{name: "IIR", desc: "Interrupt identification register",
	 swaccess: "ro", fields: [
	     {bits: "0", name: "INT", resval: "1",
	      desc: "This bit is clear if the UART is interrupting."
	     }
	     {bits: "2:1", name: "TYPE",
	      desc: '''
              If the INT bit is clear, these bits indicate the highest
              priority pending interrupt.
              '''
	      enum: [
      		 { value: "0", name: "mdm", desc: "Modem status (lowest)" },
       		 { value: "1", name: "txe", desc: "TX holding register empty" },
       		 { value: "2", name: "rxd", desc: "RX data available" },
       		 { value: "3", name: "rxl", desc: "RX line status (highest)" }
	      ]
	     }
	     {bits: "3", name: "TO",
	      desc: "This bit is set if there is a timeout interrupt pending."
	     }
	     {bits: "5", name: "F64",
	      desc: "Will always be clear because the FIFO is not 64 bytes."
	     }
	     {bits: "7:6", name: "FEN", desc: '''
	      These bits will both be clear if the FIFO is disabled
	      and both be set if it is enabled.
              '''
	     }
	 ]}
	{name: "FCR", desc: "FIFO Control Register",
	 swaccess: "wo", fields: [
	     {bits: "0", name: "FEN",
	      desc: "This bit must be set to enable the FIFOs."
	     }
	     {bits: "1", name: "CRX", desc: '''
               Writing this bit with a 1 will reset the RX fifo. The
               bit will clear after the FIFO is reset.
              '''
	     }
	     {bits: "2", name: "CTX", desc: '''
               Writing this bit with a 1 will reset the TX fifo. The
               bit will clear after the FIFO is reset.
              '''
	     }
	     {bits: "3", name: "DMAS",
	      desc: "DMA Mode Select. This bit is not used."
	     }
	     {bits: "5", name: "E64",
	      desc: "This bit is reserved because the FIFO is not 64 bytes."
	     }
	     {bits: "7:6", name: "TL",
	      desc: '''
                These two bits set the interrupt trigger level for the
                receive FIFO. The received data available interrupt
                will be set when there are at least this number of
                bytes in the receive FIFO.
              '''
	      enum: [
      		 { value: "0", name: "rxlvl1", desc: "1 Byte" },
       		 { value: "1", name: "rxlvl4", desc: "4 Bytes" },
       		 { value: "2", name: "rxlvl8", desc: "8 bytes" },
       		 { value: "3", name: "rxlvl14", desc: "14 bytes" }
	      ]
	     }
	 ]}
    ]}
      {name: "LCR", desc: "Line control register", swaccess: "rw", fields: [
       {bits: "1:0", name: "WSIZE", desc: '''
        These two bits set the word size for both transmission and reception.
	'''
       enum: [
      	   { value: "0", name: "bits5", desc: "5 bits" },
       	   { value: "1", name: "bits6", desc: "6 bits" },
       	   { value: "2", name: "bits7", desc: "7 bits" },
       	   { value: "3", name: "bits8", desc: "8 bits" }
       ]
      }
      {bits: "2", name: "STOP", desc: '''
        If this bit is clear one stop bit is used. If this bit is set
        then two stop bits are used for 6,7, and 8 bit transmission
        and 1.5 stop bits for 5 bit transmission.
	'''
      }
      {bits: "3", name: "PAR", desc: '''
        If this bit is clear parity is not used. If this bit is set
        then parity is added according to the PTYPE field.
	'''
      }
      {bits: "5:4", name: "PTYPE", desc: '''
        These two bits set the parity for both transmission and reception.
	'''
       enum: [
      	   { value: "0", name: "parodd", desc: "Odd parity" },
       	   { value: "1", name: "pareven", desc: "Even parity" },
       	   { value: "2", name: "parhigh", desc: "Parity bit always 1" },
       	   { value: "3", name: "parlow", desc: "Parity bit always 0" }
       ]
      }
      {bits: "6", name: "BRKEN", desc: '''
        If this bit is clear the line runs as normal. If set then TX
        is forced low, sending a break condition.
	'''
      }
      {bits: "7", name: "DLAB", desc: '''
        If this bit is clear the normal registers are accessed at
        offset 0 and 1. If set then the divisor latch can be accessed.
	'''
      }
    ]},
    {name: "MCR", desc: "Modem control register", swaccess: "rw", fields: [
      {bits: "0", name: "FDTR", desc: '''
        The state of this bit sets the state of the DTR pin. When
        loopback mode is selected this drives the DSR_L input.
	'''
      }
      {bits: "1", name: "FRTS", desc: '''
        The state of this bit sets the state of the RTS_L pin. When
        loopback mode is selected this drives the CTS_L input.
	'''
      }
      {bits: "2", name: "OUT1", desc: '''
        The state of this bit sets the state of the OUT1 signal. This
        is only used in loopback mode when it drives the RI input.
	'''
      }
      {bits: "3", name: "OUT2", desc: '''
        The state of this bit sets the state of the OUT2 signal. This
        is only used in loopback mode when it drives the DCD_L input.
	'''
      }
      {bits: "4", name: "LOOP", desc: '''
        This bit should be clear for normal operation. If this bit is
        set the TX pin will go high, the handshake outputs will go
        inactive and the receiver inputs are ignorred. Internally the
        transmitter is looped back to the receiver, allowing testing
        of the UART.
	'''
      }
      {bits: "5", name: "AFC", desc: '''
        If this bit is set and the FRTS bit is set the UART will
        generate RTS based on the trigger level set for the receive
        FIFO. (If FRTS is clear then RTS will be deasserted whatever
        the state of this bit.) RTS will be asserted while the FIFO
        contains fewer bytes than set in the FCR TL field. If a start
        bit is seen while the FIFO is at or above the trigger level
        then RTS will be deasserted. If the FIFO is not being emptied
        one byte above the trigger level will be received, and there
        could be one byte more to cover the source being slow to
        respond to the RTS deassertion. In addition when this bit is
        set the UART will only start trasmission of a character when
        CTS is asserted.
	'''
      }

    ]},
    {name: "LSR", desc: "Line status register", swaccess: "ro", fields: [
	{bits: "0", name: "DRDY", desc: '''
           If this bit is set there is data ready to be read from the
           receive buffer.
	   '''
	}
	{bits: "1", name: "OVR", swaccess:"rc", desc: '''
           If this bit is set then the receive FIFO has overrun and
           data has been lost. The overflow status is raised when a
           character is received and the FIFO is full, and cleared
           whenever the LSR is read. Thus the OVR bit does not
           indicate where in the data the lost character(s) happened.
	   '''
	}
	{bits: "2", name: "PE", desc: '''
           If this bit is set then the character at the head of the
           receive FIFO (i.e. the next character to be read from the
           receive buffer) has a parity error.
	'''
	}
	{bits: "3", name: "FE", desc: '''
           If this bit is set then the character at the head of the
           receive FIFO (i.e. the next character to be read from the
           receive buffer) has a framing error. The STOP bit was not
           seen as set.
	'''
	}
	{bits: "4", name: "BRK", desc: '''
           If this bit is set then the character at the head of the
           receive FIFO (i.e. the next character to be read from the
           receive buffer) is zero and was the start of a line break condition.
	   '''
	}
	{bits: "5", name: "THRE", resval: "1", desc: '''
           If this bit is set the transmitter FIFO is empty (but there may
           be a character being transmitted).
	   '''
      }
	{bits: "6", name: "TEMT", resval: "1", desc: '''
         If this bit is set the transmitter is empty. There are no
         characters in the holding register, FIFO or currently
         being transmitted.
	 '''
      }
	{bits: "7", name: "RFE", swaccess:"rc", desc: '''
        If this bit is set there is at least one character in the
        receive FIFO with a parity error or framing error or break
        condition. This bit is cleared by reading the LSR if there
        are no subsequent errors in the FIFO.
	'''
      }
    ]},
    {name: "MSR", desc: "Modem status register", swaccess: "ro", fields: [
	{bits: "0", name: "DCTS", swaccess:"rc", desc: '''
          If this bit is set the CTS input has changed since this
          register was last read. (Note that this bit is set by a
          transition on the line. If multiple transitions have happened
          then the velue in the CTS bit may be the same as in the
          last read even though this bit is set.) In loopback mode a write
          to the register with a 1 in this bit will cause the bit to be
          set (and potentially an interrupt raised), writes of 0 are ignorred.
	'''
	}
	{bits: "1", name: "DDSR", swaccess:"rc", desc: '''
          If this bit is set the DSR input has changed since this
          register was last read. (See note for DCTS) In loopback mode a write
          to the register with a 1 in this bit will cause the bit to be
          set (and potentially an interrupt raised), writes of 0 are ignorred.
	'''
	}
	{bits: "2", name: "TRI", swaccess:"rc", desc: '''
          If this bit is set a low to high transition was seen on the RI input
          since this
          register was last read. (See note for DCTS) In loopback mode a write
          to the register with a 1 in this bit will cause the bit to be
          set (and potentially an interrupt raised), writes of 0 are ignorred.
	  '''
	}
	{bits: "3", name: "DDCD", swaccess:"rc", desc: '''
          If this bit is set the DCD input has changed since this
          register was last read. (See note for DCTS) In loopback mode a write
          to the register with a 1 in this bit will cause the bit to be
          set (and potentially an interrupt raised), writes of 0 are ignorred.
	'''
	}
	{bits: "4", name: "CTS", desc: '''
           This bit reflects the state of the CTS_L input. Note that since
           CTS_L is active low, the value of this bit is the inverse of the pin.
	   '''
	}
	{bits: "5", name: "DSR", desc: '''
        This bit reflects the state of the DSR_L input. Note that since
        DSR_L is active low, the value of this bit is the inverse of the pin.
	'''
      }
      {bits: "6", name: "RI", desc: '''
        This bit reflects the state of the RI_L input. Note that since
        RI_L is active low, the value of this bit is the inverse of the pin.
	In loopback mode this bit reflects the value of OUT1 in the MCR.
        '''
      }
      {bits: "7", name: "DCD", desc: '''
        This bit reflects the state of the DCD_L input. Note that since
        DCD_L is active low, the value of this bit is the inverse of the pin.
	In loopback mode this bit reflects the value of OUT2 in the MCR.
	'''
      }
    ]},
    {name: "SCR", desc: "Scratch register", swaccess: "rw", fields: [
	{bits: "7:0", name: "scratch", resval: "x", desc: '''
        This register is not used by the hardware. Software may use it
        as a scratch register.
	'''
      }
    ]},

  ]
}