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: releng/10.2/sys/dev/uart/uart_if.m 262649 2014-03-01 04:16:54Z imp $ 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 40INTERFACE 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. 47METHOD 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. 56METHOD 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. 63METHOD 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. 75METHOD 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. 83METHOD 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. 98METHOD int ipend { 99 struct uart_softc *this; 100} 101 102# param() - set communication parameters. 103# This method is called to change the communication parameters. 104METHOD 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. 116METHOD 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. 123METHOD 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. 132METHOD 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. 141METHOD int transmit { 142 struct uart_softc *this; 143}; 144 145# grab() - Up call from the console to the upper layers of the driver when 146# the kernel asks to grab the console. This is valid only for console 147# drivers. This method is responsible for transitioning the hardware 148# from an interrupt driven state to a polled state that works with the 149# low-level console interface defined for this device. The kernel 150# currently only calls this when it wants to grab input from the 151# console. Output can still happen asyncrhonously to these calls. 152METHOD void grab { 153 struct uart_softc *this; 154}; 155 156# ungrab() - Undoes the effects of grab(). 157METHOD void ungrab { 158 struct uart_softc *this; 159}; 160