sys/dev/uart/uart_if.m

   1 #-
   2 # Copyright (c) 2003 Marcel Moolenaar
   3 # All rights reserved.
   4 #
   5 # Redistribution and use in source and binary forms, with or without
   6 # modification, are permitted provided that the following conditions
   7 # are met:
   8 #
   9 # 1. Redistributions of source code must retain the above copyright
  10 #    notice, this list of conditions and the following disclaimer.
  11 # 2. Redistributions in binary form must reproduce the above copyright
  12 #    notice, this list of conditions and the following disclaimer in the
  13 #    documentation and/or other materials provided with the distribution.
  14 #
  15 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 #
  26 # $FreeBSD$
  27
  28 #include <sys/param.h>
  29 #include <sys/systm.h>
  30 #include <sys/lock.h>
  31 #include <sys/mutex.h>
  32 #include <sys/bus.h>
  33 #include <machine/bus.h>
  34 #include <dev/uart/uart.h>
  35 #include <dev/uart/uart_bus.h>
  36
  37 # The UART hardware interface. The core UART code is hardware independent.
  38 # The details of the hardware are abstracted by the UART hardware interface.
  39
  40 INTERFACE uart;
  41
  42 # attach() - attach hardware.
  43 # This method is called when the device is being attached. All resources
  44 # have been allocated. The transmit and receive buffers exist, but no
  45 # high-level (ie tty) initialization has been done yet.
  46 # The intend of this method is to setup the hardware for normal operation.
  47 METHOD int attach {
  48         struct uart_softc *this;
  49 };
  50
  51 # detach() - detach hardware.
  52 # This method is called when a device is being detached from its bus. It
  53 # is the first action performed, so even the high-level (ie tty) interface
  54 # is still operational.
  55 # The intend of this method is to disable the hardware.
  56 METHOD int detach {
  57         struct uart_softc *this;
  58 };
  59
  60 # flush() - flush FIFOs.
  61 # This method is called to flush the transmitter and/or the receiver as
  62 # specified by the what argument. Characters are expected to be lost.
  63 METHOD int flush {
  64         struct uart_softc *this;
  65         int     what;
  66 };
  67
  68 # getsig() - get line and modem signals.
  69 # This method retrieves the DTE and DCE signals and their corresponding
  70 # delta bits. The delta bits include those corresponding to DTE signals
  71 # when they were changed by a call to setsig. The delta bits maintained
  72 # by the hardware driver are cleared as a side-effect. A second call to
  73 # this function will not have any delta bits set, unless there was a
  74 # change in the signals in the mean time.
  75 METHOD int getsig {
  76         struct uart_softc *this;
  77 };
  78
  79 # ioctl() - get or set miscellaneous parameters.
  80 # This method is the bitbucket method. It can (and will) be used when there's
  81 # something we need to set or get for which a new method is overkill. It's
  82 # used for example to set HW or SW flow-control.
  83 METHOD int ioctl {
  84         struct uart_softc *this;
  85         int request;
  86         intptr_t data;
  87 };
  88
  89 # ipend() - query UART for pending interrupts.
  90 # When an interrupt is signalled, the handler will call this method to find
  91 # out which of the interrupt sources needs attention. The handler will use
  92 # this information to dispatch service routines that deal with each of the
  93 # interrupt sources. An advantage of this approach is that it allows multi-
  94 # port drivers (like puc(4)) to query multiple devices concurrently and
  95 # service them on an interrupt priority basis. If the hardware cannot provide
  96 # the information reliably, it is free to service the interrupt and return 0,
  97 # meaning that no attention is required.
  98 METHOD int ipend {
  99         struct uart_softc *this;
 100 }
 101
 102 # param() - set communication parameters.
 103 # This method is called to change the communication parameters.
 104 METHOD int param {
 105         struct uart_softc *this;
 106         int     baudrate;
 107         int     databits;
 108         int     stopbits;
 109         int     parity;
 110 };
 111
 112 # probe() - detect hardware.
 113 # This method is called as part of the bus probe to make sure the
 114 # hardware exists. This function should also set the device description
 115 # to something that represents the hardware.
 116 METHOD int probe {
 117         struct uart_softc *this;
 118 };
 119
 120 # receive() - move data from the receive FIFO to the receive buffer.
 121 # This method is called to move received data to the receive buffer and
 122 # additionally should make sure the receive interrupt should be cleared.
 123 METHOD int receive {
 124         struct uart_softc *this;
 125 };
 126
 127 # setsig() - set line and modem signals.
 128 # This method allows changing DTE signals. The DTE delta bits indicate which
 129 # signals are to be changed and the DTE bits themselves indicate whether to
 130 # set or clear the signals. A subsequent call to getsig will return with the
 131 # DTE delta bits set of those DTE signals that did change by this method.
 132 METHOD int setsig {
 133         struct uart_softc *this;
 134         int     sig;
 135 };
 136
 137 # transmit() - move data from the transmit buffer to the transmit FIFO.
 138 # This method is responsible for writing the Tx buffer to the UART and
 139 # additionally should make sure that a transmit interrupt is generated
 140 # when transmission is complete.
 141 METHOD int transmit {
 142         struct uart_softc *this;
 143 };