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/lock.h>
  30 #include <sys/mutex.h>
  31 #include <sys/bus.h>
  32 #include <machine/bus.h>
  33 #include <dev/uart/uart.h>
  34 #include <dev/uart/uart_bus.h>
  35
  36 # The UART hardware interface. The core UART code is hardware independent.
  37 # The details of the hardware are abstracted by the UART hardware interface.
  38
  39 INTERFACE uart;
  40
  41 # attach() - attach hardware.
  42 # This method is called when the device is being attached. All resources
  43 # have been allocated. The transmit and receive buffers exist, but no
  44 # high-level (ie tty) initialization has been done yet.
  45 # The intend of this method is to setup the hardware for normal operation.
  46 METHOD int attach {
  47         struct uart_softc *this;
  48 };
  49
  50 # detach() - detach hardware.
  51 # This method is called when a device is being detached from its bus. It
  52 # is the first action performed, so even the high-level (ie tty) interface
  53 # is still operational.
  54 # The intend of this method is to disable the hardware.
  55 METHOD int detach {
  56         struct uart_softc *this;
  57 };
  58
  59 # flush() - flush FIFOs.
  60 # This method is called to flush the transmitter and/or the receiver as
  61 # specified by the what argument. Characters are expected to be lost.
  62 METHOD int flush {
  63         struct uart_softc *this;
  64         int     what;
  65 };
  66
  67 # getsig() - get line and modem signals.
  68 # This method retrieves the DTE and DCE signals and their corresponding
  69 # delta bits. The delta bits include those corresponding to DTE signals
  70 # when they were changed by a call to setsig. The delta bits maintained
  71 # by the hardware driver are cleared as a side-effect. A second call to
  72 # this function will not have any delta bits set, unless there was a
  73 # change in the signals in the mean time.
  74 METHOD int getsig {
  75         struct uart_softc *this;
  76 };
  77
  78 # ioctl() - get or set miscellaneous parameters.
  79 # This method is the bitbucket method. It can (and will) be used when there's
  80 # something we need to set or get for which a new method is overkill. It's
  81 # used for example to set HW or SW flow-control.
  82 METHOD int ioctl {
  83         struct uart_softc *this;
  84         int request;
  85         intptr_t data;
  86 };
  87
  88 # ipend() - query UART for pending interrupts.
  89 # When an interrupt is signalled, the handler will call this method to find
  90 # out which of the interrupt sources needs attention. The handler will use
  91 # this information to dispatch service routines that deal with each of the
  92 # interrupt sources. An advantage of this approach is that it allows multi-
  93 # port drivers (like puc(4)) to query multiple devices concurrently and
  94 # service them on an interrupt priority basis. If the hardware cannot provide
  95 # the information reliably, it is free to service the interrupt and return 0,
  96 # meaning that no attention is required.
  97 METHOD int ipend {
  98         struct uart_softc *this;
  99 }
 100
 101 # param() - set communication parameters.
 102 # This method is called to change the communication parameters.
 103 METHOD int param {
 104         struct uart_softc *this;
 105         int     baudrate;
 106         int     databits;
 107         int     stopbits;
 108         int     parity;
 109 };
 110
 111 # probe() - detect hardware.
 112 # This method is called as part of the bus probe to make sure the
 113 # hardware exists. This function should also set the device description
 114 # to something that represents the hardware.
 115 METHOD int probe {
 116         struct uart_softc *this;
 117 };
 118
 119 # receive() - move data from the receive FIFO to the receive buffer.
 120 # This method is called to move received data to the receive buffer and
 121 # additionally should make sure the receive interrupt should be cleared.
 122 METHOD int receive {
 123         struct uart_softc *this;
 124 };
 125
 126 # setsig() - set line and modem signals.
 127 # This method allows changing DTE signals. The DTE delta bits indicate which
 128 # signals are to be changed and the DTE bits themselves indicate whether to
 129 # set or clear the signals. A subsequent call to getsig will return with the
 130 # DTE delta bits set of those DTE signals that did change by this method.
 131 METHOD int setsig {
 132         struct uart_softc *this;
 133         int     sig;
 134 };
 135
 136 # transmit() - move data from the transmit buffer to the transmit FIFO.
 137 # This method is responsible for writing the Tx buffer to the UART and
 138 # additionally should make sure that a transmit interrupt is generated
 139 # when transmission is complete.
 140 METHOD int transmit {
 141         struct uart_softc *this;
 142 };