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