share/man/man4/altera_jtag_uart.4

   1 .\"-
   2 .\" Copyright (c) 2012 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed by SRI International and the University of
   6 .\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237)
   7 .\" ("CTSRD"), as part of the DARPA CRASH research programme.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd August 18, 2012
  33 .Dt ALTERA_JTAG_UART 4
  34 .Os
  35 .Sh NAME
  36 .Nm altera_jtag_uart
  37 .Nd driver for the Altera JTAG UART Core
  38 .Sh SYNOPSIS
  39 .Cd "device altera_jtag_uart"
  40 .Pp
  41 In
  42 .Pa /boot/device.hints :
  43 .Cd hint.altera_jtag_uart.0.at="nexus0"
  44 .Cd hint.altera_jtag_uart.0.maddr=0x7f000000
  45 .Cd hint.altera_jtag_uart.0.msize=0x40
  46 .Cd hint.altera_jtag_uart.0.irq=0
  47 .Cd hint.altera_jtag_uart.1.at="nexus0"
  48 .Cd hint.altera_jtag_uart.1.maddr=0x7f001000
  49 .Cd hint.altera_jtag_uart.1.msize=0x40
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 device driver provides support for the Altera JTAG UART core, which allows
  54 multiple UART-like streams to be carried over JTAG.
  55 .Nm
  56 allows JTAG UART streams to be attached to both the low-level console
  57 interface, used for direct kernel input and output, and the
  58 .Xr tty 4
  59 layer, to be used with
  60 .Xr ttys 5
  61 and
  62 .Xr login 1 .
  63 Sequential Altera JTAG UART devices will appear as
  64 .Li ttyu0 ,
  65 .Li ttyu1 ,
  66 etc.
  67 .Sh HARDWARE
  68 Altera JTAG UART devices can be connected to using Altera's
  69 .Pa nios2-terminal
  70 program, with the instance selected using the
  71 .Li --instance
  72 argument on the management host.
  73 .Nm
  74 supports JTAG UART cores with or without interrupt lines connected; if the
  75 .Li irq
  76 portion of the
  77 .Pa device.hints
  78 entry is omitted, the driver will poll rather than configure interrupts.
  79 .Sh SEE ALSO
  80 .Xr login 1 ,
  81 .Xr tty 4 ,
  82 .Xr ttys 5
  83 .Rs
  84 .%T Altera Embedded Peripherals IP User Guide
  85 .%D June 2011
  86 .%I Altera Corporation
  87 .%U http://www.altera.com/literature/ug/ug_embedded_ip.pdf
  88 .Re
  89 .Sh HISTORY
  90 The
  91 .Nm
  92 device driver first appeared in
  93 .Fx 10.0 .
  94 .Sh AUTHORS
  95 The
  96 .Nm
  97 device driver and this manual page were
  98 developed by SRI International and the University of Cambridge Computer
  99 Laboratory under DARPA/AFRL contract
 100 .Pq FA8750-10-C-0237
 101 .Pq Do CTSRD Dc ,
 102 as part of the DARPA CRASH research programme.
 103 This device driver was written by
 104 .An Robert N. M. Watson .
 105 .Sh BUGS
 106 .Nm
 107 must dynamically poll to detect when JTAG is present, in order to disable flow
 108 control in the event that there is no receiving endpoint.
 109 Otherwise, the boot may hang waiting for the JTAG client to be attached, and
 110 user processes attached to JTAG UART devices might block indefinitely.
 111 However, there is no way to flush the output buffer once JTAG is detected to
 112 have disappeared; this means that a small amount of stale output data will
 113 remain in the output buffer, being displayed by
 114 .Li nios2-terminal
 115 when it is connected.
 116 Loss of JTAG will not generate a hang-up event, as that is rarely the desired
 117 behaviour.
 118 .Pp
 119 .Li nios2-terminal
 120 does not place the client-side TTY in raw mode, and so by default will not
 121 pass all control characters through to the UART.