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