gcc/ada/libgnat/g-sercom.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --           G N A T . S E R I A L _ C O M M U N I C A T I O N S            --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --                    Copyright (C) 2007-2023, AdaCore                      --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
  17 --                                                                          --
  18 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 --  Serial communications package, implemented on Windows and GNU/Linux
  33
  34 with Ada.Streams;
  35 with Interfaces.C;
  36 with System.OS_Constants;
  37
  38 package GNAT.Serial_Communications is
  39
  40    --  Following is a simple example of using GNAT.Serial_Communications.
  41    --
  42    --  with Ada.Streams;
  43    --  with GNAT.Serial_Communications;
  44    --
  45    --  procedure Serial is
  46    --     use Ada.Streams;
  47    --     use GNAT;
  48    --
  49    --     subtype Message is Stream_Element_Array (1 .. 20);
  50    --
  51    --     Data   : constant String (1 .. 20)  := "ABCDEFGHIJLKMNOPQRST";
  52    --     Buffer : Message;
  53    --
  54    --     S_Port : constant Natural := 5;
  55    --     --  Serial port number
  56    --
  57    --  begin
  58    --     --  Convert message (String -> Stream_Element_Array)
  59    --
  60    --     for K in Data'Range loop
  61    --        Buffer (Stream_Element_Offset (K)) := Character'Pos (Data (K));
  62    --     end loop;
  63    --
  64    --     declare
  65    --        Port_Name : constant Serial_Communications.Port_Name :=
  66    --                      Serial_Communications.Name (Number => S_Port);
  67    --        Port      : Serial_Communications.Serial_Port;
  68    --
  69    --     begin
  70    --        Serial_Communications.Open
  71    --          (Port => Port,
  72    --           Name => Port_Name);
  73    --
  74    --        Serial_Communications.Set
  75    --          (Port      => Port,
  76    --           Rate      => Serial_Communications.B9600,
  77    --           Bits      => Serial_Communications.CS8,
  78    --           Stop_Bits => Serial_Communications.One,
  79    --           Parity    => Serial_Communications.Even);
  80    --
  81    --        Serial_Communications.Write
  82    --          (Port   => Port,
  83    --           Buffer => Buffer);
  84    --
  85    --        Serial_Communications.Close
  86    --          (Port => Port);
  87    --     end;
  88    --  end Serial;
  89
  90    Serial_Error : exception;
  91    --  Raised when a communication problem occurs
  92
  93    type Port_Name is new String;
  94    --  A serial com port name
  95
  96    function Name (Number : Positive) return Port_Name;
  97    --  Returns a possible port name for the given legacy PC architecture serial
  98    --  port number (COM<number>: on Windows, ttyS<number-1> on Linux).
  99    --  Note that this function does not support other kinds of serial ports
 100    --  nor operating systems other than Windows and Linux. For all other
 101    --  cases, an explicit port name can be passed directly to Open.
 102
 103    type Data_Rate is
 104      (B75, B110, B150, B300, B600, B1200,
 105       B2400, B4800, B9600,
 106       B19200, B38400, B57600, B115200,
 107       B230400, B460800, B500000, B576000, B921600,
 108       B1000000, B1152000, B1500000,
 109       B2000000, B2500000, B3000000,
 110       B3500000, B4000000);
 111    --  Speed of the communication
 112
 113    type Data_Bits is (CS8, CS7);
 114    --  Communication bits
 115
 116    type Stop_Bits_Number is (One, Two);
 117    --  One or two stop bits
 118
 119    type Parity_Check is (None, Even, Odd);
 120    --  Either no parity check or an even or odd parity
 121
 122    type Flow_Control is (None, RTS_CTS, Xon_Xoff);
 123    --  No flow control, hardware flow control, software flow control
 124
 125    type Serial_Port is new Ada.Streams.Root_Stream_Type with private;
 126    --  Serial port stream type
 127
 128    type Serial_Port_Descriptor is
 129      new System.OS_Constants.Serial_Port_Descriptor;
 130    --  OS specific serial port descriptor
 131
 132    procedure Open
 133      (Port : out Serial_Port;
 134       Name : Port_Name);
 135    --  Open the given port name. Raises Serial_Error if the port cannot be
 136    --  opened.
 137
 138    procedure Set
 139      (Port      : Serial_Port;
 140       Rate      : Data_Rate        := B9600;
 141       Bits      : Data_Bits        := CS8;
 142       Stop_Bits : Stop_Bits_Number := One;
 143       Parity    : Parity_Check     := None;
 144       Block     : Boolean          := True;
 145       Local     : Boolean          := True;
 146       Flow      : Flow_Control     := None;
 147       Timeout   : Duration         := 10.0);
 148    --  The communication port settings. If Block is set then a read call
 149    --  will wait for the whole buffer to be filed. If Block is not set then
 150    --  the given Timeout (in seconds) is used. If Local is set then modem
 151    --  control lines (in particular DCD) are ignored (not supported on
 152    --  Windows). Flow indicates the flow control type as defined above.
 153
 154    --  Note: the timeout precision may be limited on some implementation
 155    --  (e.g. on GNU/Linux the maximum precision is a tenth of seconds).
 156
 157    --  Note: calling this procedure may reinitialize the serial port hardware
 158    --  and thus cause loss of some buffered data if used during communication.
 159
 160    overriding procedure Read
 161      (Port   : in out Serial_Port;
 162       Buffer : out Ada.Streams.Stream_Element_Array;
 163       Last   : out Ada.Streams.Stream_Element_Offset);
 164    --  Read a set of bytes, put result into Buffer and set Last accordingly.
 165    --  Last is set to Buffer'First - 1 if no byte has been read, unless
 166    --  Buffer'First = Stream_Element_Offset'First, in which case the exception
 167    --  Constraint_Error is raised instead.
 168
 169    overriding procedure Write
 170      (Port   : in out Serial_Port;
 171       Buffer : Ada.Streams.Stream_Element_Array);
 172    --  Write buffer into the port
 173
 174    procedure Close (Port : in out Serial_Port);
 175    --  Close port
 176
 177    procedure To_Ada (Port : out Serial_Port; Fd : Serial_Port_Descriptor)
 178      with Inline;
 179    --  Convert a serial port descriptor to Serial_Port. This is useful when a
 180    --  serial port descriptor is obtained from an external library call.
 181
 182    function To_C
 183      (Port : Serial_Port) return Serial_Port_Descriptor with Inline;
 184    --  Return a serial port descriptor to be used by external subprograms.
 185    --  This is useful for C functions that are not yet interfaced in this
 186    --  package.
 187
 188 private
 189
 190    type Serial_Port is new Ada.Streams.Root_Stream_Type with record
 191       H : Serial_Port_Descriptor := -1;
 192    end record;
 193
 194    Data_Rate_Value : constant array (Data_Rate) of Interfaces.C.unsigned :=
 195                        [B75      =>        75,
 196                         B110     =>       110,
 197                         B150     =>       150,
 198                         B300     =>       300,
 199                         B600     =>       600,
 200                         B1200    =>     1_200,
 201                         B2400    =>     2_400,
 202                         B4800    =>     4_800,
 203                         B9600    =>     9_600,
 204                         B19200   =>    19_200,
 205                         B38400   =>    38_400,
 206                         B57600   =>    57_600,
 207                         B115200  =>   115_200,
 208                         B230400  =>   230_400,
 209                         B460800  =>   460_800,
 210                         B500000  =>   500_000,
 211                         B576000  =>   576_000,
 212                         B921600  =>   921_600,
 213                         B1000000 => 1_000_000,
 214                         B1152000 => 1_152_000,
 215                         B1500000 => 1_500_000,
 216                         B2000000 => 2_000_000,
 217                         B2500000 => 2_500_000,
 218                         B3000000 => 3_000_000,
 219                         B3500000 => 3_500_000,
 220                         B4000000 => 4_000_000];
 221
 222    function To_C (Port : Serial_Port) return Serial_Port_Descriptor is
 223       (Port.H);
 224
 225 end GNAT.Serial_Communications;