1139749Simp#- 2119815Smarcel# Copyright (c) 2003 Marcel Moolenaar 3119815Smarcel# All rights reserved. 4119815Smarcel# 5119815Smarcel# Redistribution and use in source and binary forms, with or without 6119815Smarcel# modification, are permitted provided that the following conditions 7119815Smarcel# are met: 8119815Smarcel# 9119815Smarcel# 1. Redistributions of source code must retain the above copyright 10119815Smarcel# notice, this list of conditions and the following disclaimer. 11119815Smarcel# 2. Redistributions in binary form must reproduce the above copyright 12119815Smarcel# notice, this list of conditions and the following disclaimer in the 13119815Smarcel# documentation and/or other materials provided with the distribution. 14119815Smarcel# 15119815Smarcel# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16119815Smarcel# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17119815Smarcel# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18119815Smarcel# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19119815Smarcel# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20119815Smarcel# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21119815Smarcel# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22119815Smarcel# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23119815Smarcel# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24119815Smarcel# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25119815Smarcel# 26119815Smarcel# $FreeBSD: releng/10.2/sys/dev/uart/uart_if.m 262649 2014-03-01 04:16:54Z imp $ 27119815Smarcel 28120143Smarcel#include <sys/param.h> 29234194Sgrehan#include <sys/systm.h> 30120143Smarcel#include <sys/lock.h> 31120143Smarcel#include <sys/mutex.h> 32119815Smarcel#include <sys/bus.h> 33119815Smarcel#include <machine/bus.h> 34119815Smarcel#include <dev/uart/uart.h> 35119815Smarcel#include <dev/uart/uart_bus.h> 36119815Smarcel 37119815Smarcel# The UART hardware interface. The core UART code is hardware independent. 38119815Smarcel# The details of the hardware are abstracted by the UART hardware interface. 39119815Smarcel 40119815SmarcelINTERFACE uart; 41119815Smarcel 42119815Smarcel# attach() - attach hardware. 43119815Smarcel# This method is called when the device is being attached. All resources 44119815Smarcel# have been allocated. The transmit and receive buffers exist, but no 45119815Smarcel# high-level (ie tty) initialization has been done yet. 46119815Smarcel# The intend of this method is to setup the hardware for normal operation. 47119815SmarcelMETHOD int attach { 48119815Smarcel struct uart_softc *this; 49119815Smarcel}; 50119815Smarcel 51119815Smarcel# detach() - detach hardware. 52119815Smarcel# This method is called when a device is being detached from its bus. It 53119815Smarcel# is the first action performed, so even the high-level (ie tty) interface 54119815Smarcel# is still operational. 55119815Smarcel# The intend of this method is to disable the hardware. 56119815SmarcelMETHOD int detach { 57119815Smarcel struct uart_softc *this; 58119815Smarcel}; 59119815Smarcel 60119815Smarcel# flush() - flush FIFOs. 61119815Smarcel# This method is called to flush the transmitter and/or the receiver as 62119815Smarcel# specified by the what argument. Characters are expected to be lost. 63119815SmarcelMETHOD int flush { 64119815Smarcel struct uart_softc *this; 65119815Smarcel int what; 66119815Smarcel}; 67119815Smarcel 68119815Smarcel# getsig() - get line and modem signals. 69119815Smarcel# This method retrieves the DTE and DCE signals and their corresponding 70119815Smarcel# delta bits. The delta bits include those corresponding to DTE signals 71119815Smarcel# when they were changed by a call to setsig. The delta bits maintained 72119815Smarcel# by the hardware driver are cleared as a side-effect. A second call to 73119815Smarcel# this function will not have any delta bits set, unless there was a 74119815Smarcel# change in the signals in the mean time. 75119815SmarcelMETHOD int getsig { 76119815Smarcel struct uart_softc *this; 77119815Smarcel}; 78119815Smarcel 79119815Smarcel# ioctl() - get or set miscellaneous parameters. 80119815Smarcel# This method is the bitbucket method. It can (and will) be used when there's 81119815Smarcel# something we need to set or get for which a new method is overkill. It's 82119815Smarcel# used for example to set HW or SW flow-control. 83119815SmarcelMETHOD int ioctl { 84119815Smarcel struct uart_softc *this; 85119815Smarcel int request; 86119815Smarcel intptr_t data; 87119815Smarcel}; 88119815Smarcel 89119815Smarcel# ipend() - query UART for pending interrupts. 90119815Smarcel# When an interrupt is signalled, the handler will call this method to find 91119815Smarcel# out which of the interrupt sources needs attention. The handler will use 92119815Smarcel# this information to dispatch service routines that deal with each of the 93119815Smarcel# interrupt sources. An advantage of this approach is that it allows multi- 94119815Smarcel# port drivers (like puc(4)) to query multiple devices concurrently and 95119815Smarcel# service them on an interrupt priority basis. If the hardware cannot provide 96119815Smarcel# the information reliably, it is free to service the interrupt and return 0, 97119815Smarcel# meaning that no attention is required. 98119815SmarcelMETHOD int ipend { 99119815Smarcel struct uart_softc *this; 100119815Smarcel} 101119815Smarcel 102119815Smarcel# param() - set communication parameters. 103119815Smarcel# This method is called to change the communication parameters. 104119815SmarcelMETHOD int param { 105119815Smarcel struct uart_softc *this; 106119815Smarcel int baudrate; 107119815Smarcel int databits; 108119815Smarcel int stopbits; 109119815Smarcel int parity; 110119815Smarcel}; 111119815Smarcel 112119815Smarcel# probe() - detect hardware. 113119815Smarcel# This method is called as part of the bus probe to make sure the 114119815Smarcel# hardware exists. This function should also set the device description 115119815Smarcel# to something that represents the hardware. 116119815SmarcelMETHOD int probe { 117119815Smarcel struct uart_softc *this; 118119815Smarcel}; 119119815Smarcel 120119815Smarcel# receive() - move data from the receive FIFO to the receive buffer. 121119815Smarcel# This method is called to move received data to the receive buffer and 122119815Smarcel# additionally should make sure the receive interrupt should be cleared. 123119815SmarcelMETHOD int receive { 124119815Smarcel struct uart_softc *this; 125119815Smarcel}; 126119815Smarcel 127119815Smarcel# setsig() - set line and modem signals. 128119815Smarcel# This method allows changing DTE signals. The DTE delta bits indicate which 129119815Smarcel# signals are to be changed and the DTE bits themselves indicate whether to 130119815Smarcel# set or clear the signals. A subsequent call to getsig will return with the 131119815Smarcel# DTE delta bits set of those DTE signals that did change by this method. 132119815SmarcelMETHOD int setsig { 133119815Smarcel struct uart_softc *this; 134119815Smarcel int sig; 135119815Smarcel}; 136119815Smarcel 137119815Smarcel# transmit() - move data from the transmit buffer to the transmit FIFO. 138119815Smarcel# This method is responsible for writing the Tx buffer to the UART and 139119815Smarcel# additionally should make sure that a transmit interrupt is generated 140119815Smarcel# when transmission is complete. 141119815SmarcelMETHOD int transmit { 142119815Smarcel struct uart_softc *this; 143119815Smarcel}; 144262649Simp 145262649Simp# grab() - Up call from the console to the upper layers of the driver when 146262649Simp# the kernel asks to grab the console. This is valid only for console 147262649Simp# drivers. This method is responsible for transitioning the hardware 148262649Simp# from an interrupt driven state to a polled state that works with the 149262649Simp# low-level console interface defined for this device. The kernel 150262649Simp# currently only calls this when it wants to grab input from the 151262649Simp# console. Output can still happen asyncrhonously to these calls. 152262649SimpMETHOD void grab { 153262649Simp struct uart_softc *this; 154262649Simp}; 155262649Simp 156262649Simp# ungrab() - Undoes the effects of grab(). 157262649SimpMETHOD void ungrab { 158262649Simp struct uart_softc *this; 159262649Simp}; 160