include/libchip/serial.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @brief  The generic libchip serial driver interface
0007  */
0008
0009
0010 /*
0011  *  This file contains the TTY driver table definition
0012  *
0013  *  This driver uses the termios pseudo driver.
0014  *
0015  *  COPYRIGHT (c) 1989-1999.
0016  *  On-Line Applications Research Corporation (OAR).
0017  *
0018  * Redistribution and use in source and binary forms, with or without
0019  * modification, are permitted provided that the following conditions
0020  * are met:
0021  * 1. Redistributions of source code must retain the above copyright
0022  *    notice, this list of conditions and the following disclaimer.
0023  * 2. Redistributions in binary form must reproduce the above copyright
0024  *    notice, this list of conditions and the following disclaimer in the
0025  *    documentation and/or other materials provided with the distribution.
0026  *
0027  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0028  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0029  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0030  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0031  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0032  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0033  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0034  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0035  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0036  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0037  * POSSIBILITY OF SUCH DAMAGE.
0038  */
0039
0040 #ifndef __LIBCHIP_SERIAL_h
0041 #define __LIBCHIP_SERIAL_h
0042
0043 #include <termios.h>
0044
0045 #include <rtems.h>
0046
0047 #ifdef __cplusplus
0048 extern "C" {
0049 #endif
0050
0051 /*
0052  *  Types for get and set register routines
0053  */
0054
0055 /**
0056  *  @typedef getRegister_f
0057  *
0058  *  This type function provides a hook for the bsp specific method
0059  *  that gets register data from the given port and register.
0060  */
0061 typedef uint8_t   (*getRegister_f)(uintptr_t port, uint8_t reg);
0062
0063 /**
0064  *  @typedef setData_f
0065  *
0066  *  This type function provides a hook for the bsp specific method
0067  *  that sets register data from the given port and register to the
0068  *  given value.
0069  */
0070 typedef void      (*setRegister_f)(uintptr_t port, uint8_t reg, uint8_t  value);
0071
0072 /**
0073  *  @typedef getData_f
0074  *
0075  *  This type function provides a hook for the bsp specific method
0076  *  that gets data from the specified port.
0077  */
0078 typedef uint8_t   (*getData_f)(uintptr_t port);
0079
0080 /**
0081  *  @typedef setData_f
0082  *
0083  *  This type function provides a hook for the bsp specific method
0084  *  that writes value to the specified port.
0085  */
0086 typedef void      (*setData_f)(uintptr_t port, uint8_t value);
0087
0088 /**
0089  *  @typedef _console_fns
0090  *
0091  *  This type definition provides a structure of functions each
0092  *  methood provides an interfce to the serial por to do a specific
0093  *  function.
0094  */
0095 typedef struct _console_fns {
0096   bool    (*deviceProbe)(int minor);
0097   int     (*deviceFirstOpen)(int major, int minor, void *arg);
0098   int     (*deviceLastClose)(int major, int minor, void *arg);
0099   int     (*deviceRead)(int minor);
0100   ssize_t (*deviceWrite)(int minor, const char *buf, size_t len);
0101   void    (*deviceInitialize)(int minor);
0102   void    (*deviceWritePolled)(int minor, char cChar);
0103   int     (*deviceSetAttributes)(int minor, const struct termios *t);
0104   bool      deviceOutputUsesInterrupts;
0105 } console_fns;
0106
0107 /**
0108  *  @typedef _console_flow
0109  *
0110  *  This type definition provides a structure of functions
0111  *  that provide flow control for the transmit buffer.
0112  */
0113 typedef struct _console_flow {
0114   int (*deviceStopRemoteTx)(int minor);
0115   int (*deviceStartRemoteTx)(int minor);
0116 } console_flow;
0117
0118
0119 /**
0120  * This type defination provides an enumerated type of all
0121  * supported libchip console drivers.
0122  */
0123 typedef enum {
0124   SERIAL_MC68681,              /* Motorola MC68681 or Exar 88681 */
0125   SERIAL_NS16550,              /* National Semiconductor NS16550 */
0126   SERIAL_NS16550_WITH_FDR,     /* National Semiconductor NS16550
0127                                   with Fractional Divider Register (FDR) */
0128   SERIAL_Z85C30,               /* Zilog Z85C30 */
0129   SERIAL_CUSTOM                /* BSP specific driver */
0130 } console_devs;
0131
0132 /**
0133  * This type defination provides an structure that is used to
0134  * uniquely identify a specific serial port.
0135  */
0136 typedef struct _console_tbl {
0137   /**  This is the name of the device. */
0138   const char    *sDeviceName;
0139   /** This indicates the chip type.  It is especially important when
0140    *   multiple devices share the same interrupt vector and must be
0141    *   distinguished.
0142    */
0143   console_devs   deviceType;
0144   /** pDeviceFns   This is a pointer to the set of driver routines to use. */
0145   const console_fns *pDeviceFns;
0146   /** This value is passed to the serial device driver for use.  In termios
0147    *  itself the number is ignored.
0148    */
0149   bool         (*deviceProbe)(int minor);
0150   /** This is a pointer to the set of flow control routines to
0151    *  use. Serial device drivers will typically supply RTSCTS
0152    *  and DTRCTS handshake routines for DCE to DCE communication,
0153    *  however for DCE to DTE communication, no such routines
0154    *  should be necessary as RTS will be driven automatically
0155    *  when the transmitter is active.
0156    */
0157   const console_flow *pDeviceFlow;
0158   /** The high water mark in the input buffer is set to the buffer
0159    *  size less ulMargin. Once this level is reached, the driver's
0160    *  flow control routine used to stop the remote transmitter will
0161    *  be called. This figure should be greater than or equal to
0162    *  the number of stages of FIFO between the transmitter and
0163    *  receiver.
0164    *
0165    *  @note At the current time, this parameter is hard coded
0166    *        in termios and this number is ignored.
0167    */
0168   uint32_t       ulMargin;
0169   /** After the high water mark specified by ulMargin has been
0170    *  reached, the driver's routine to re-start the remote
0171    *  transmitter will be called once the level in the input
0172    *  buffer has fallen by ulHysteresis bytes.
0173    *
0174    *  @note At the current time, this parameter is hard coded in termios.
0175    */
0176   uint32_t       ulHysteresis;
0177   /** This contains either device specific data or a pointer to a
0178    *  device specific structure containing additional information
0179    *  not provided in this table.
0180    */
0181   void          *pDeviceParams;
0182   /** This is the primary control port number for the device. This
0183    *  may be used to specify different instances of the same device type.
0184    */
0185   uint32_t       ulCtrlPort1;
0186   /** This is the secondary control port number, of use when a given
0187    *  device has more than one available channel.
0188    */
0189   uint32_t       ulCtrlPort2;
0190   /** This is the port number for the data port of the device */
0191   uint32_t       ulDataPort;
0192   /** This is the routine used to read register values. */
0193   getRegister_f  getRegister;
0194   /** This is the routine used to write register values. */
0195   setRegister_f  setRegister;
0196   /** This is the routine used to read the data register (RX). */
0197   getData_f      getData;
0198   /* This is the routine used to write the data register (TX). */
0199   setData_f      setData;
0200   /** This is the baud rate clock speed.*/
0201   uint32_t       ulClock;
0202   /** This encodes the interrupt vector of the device. */
0203   unsigned int   ulIntVector;
0204 } console_tbl;
0205
0206 /**
0207  * This type defination provides data for the console port.
0208  */
0209 typedef struct _console_data {
0210   void                   *termios_data;
0211   volatile bool           bActive;
0212   /** This field may be used for any purpose required by the driver  */
0213   void                   *pDeviceContext;
0214 } console_data;
0215
0216 /**
0217  *  This is a dynamically sized set of tables containing the serial
0218  *  port information.
0219  */
0220 extern console_tbl   **Console_Port_Tbl;
0221 /**
0222  * This is the number of serial ports defined in the Console_Port_Tbl.
0223  */
0224 extern unsigned long   Console_Port_Count;
0225
0226 /**
0227  *  The statically configured serial port information tables which
0228  *  are used to initially populate the dynamic tables.
0229  */
0230 extern console_tbl    Console_Configuration_Ports[];
0231 /**
0232  * The number of serial ports defined in Console_Configuration_Ports
0233  * */
0234 extern unsigned long  Console_Configuration_Count;
0235
0236 /**
0237  *  This is an array of per port information.
0238  */
0239 extern console_data  *Console_Port_Data;
0240
0241 extern rtems_device_minor_number Console_Port_Minor;
0242
0243 /**
0244  * @brief Selects the minor number of the console device.
0245  *
0246  * @see Console_Port_Minor.
0247  */
0248 void bsp_console_select(void);
0249
0250 #ifdef __cplusplus
0251 }
0252 #endif
0253
0254 #endif