blob: 9325ddcbca526b449df5faa7fdfd9c6f361be12a [file] [log] [blame]
------------------------------------------------------------------------------
-- --
-- GNAT RUN-TIME COMPONENTS --
-- --
-- S Y S T E M . B I T F I E L D _ U T I L S --
-- --
-- S p e c --
-- --
-- Copyright (C) 2019-2022, Free Software Foundation, Inc. --
-- --
-- GNAT is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
-- ware Foundation; either version 3, or (at your option) any later ver- --
-- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE. --
-- --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception, --
-- version 3.1, as published by the Free Software Foundation. --
-- --
-- You should have received a copy of the GNU General Public License and --
-- a copy of the GCC Runtime Library Exception along with this program; --
-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
-- <http://www.gnu.org/licenses/>. --
-- --
-- GNAT was originally developed by the GNAT team at New York University. --
-- Extensive contributions were provided by Ada Core Technologies Inc. --
-- --
------------------------------------------------------------------------------
package System.Bitfield_Utils is
-- This package provides a procedure for copying arbitrarily large and
-- arbitrarily bit-aligned bit fields.
-- Type Val is used to represent small bit fields. Val_2 represents a
-- contiguous pair of Vals. Val_2'Alignment is half of its size in bytes,
-- which is likely not the natural alignment. This is done to ensure that
-- any bit field that fits in a Val can fit in an aligned Val_2, starting
-- somewhere in the first half, and possibly crossing over into the second
-- half. This allows us to isolate a Val value by shifting and masking the
-- Val_2.
--
-- Val can be 8, 16, or 32 bits; larger values are more efficient. It can't
-- be 64 bits, because we need Val_2 to be a double-wide shiftable type,
-- and 128 bits is not supported. Instantiating with an 8-bit Val is useful
-- for testing and debugging; 32 bits should be used for production.
--
-- We use modular types here, not because we want modular arithmetic, but
-- so we can do shifting and masking. The actual for Val_2 should have
-- pragma Provide_Shift_Operators, so that the Shift_Left and Shift_Right
-- intrinsics can be passed in. It is impossible to put that pragma on a
-- generic formal, or on a type derived from a generic formal, so they have
-- to be passed in.
--
-- Endian indicates whether we're on a little- or big-endian machine.
pragma Elaborate_Body;
Little : constant Bit_Order := Low_Order_First;
Big : constant Bit_Order := High_Order_First;
generic
type Val is mod <>;
type Val_2 is mod <>;
with function Shift_Left
(Value : Val_2;
Amount : Natural) return Val_2 is <>;
with function Shift_Right
(Value : Val_2;
Amount : Natural) return Val_2 is <>;
Endian : Bit_Order := Default_Bit_Order;
package G is
-- Assert that Val has one of the allowed sizes, and that Val_2 is twice
-- that.
pragma Assert (Val'Size in 8 | 16 | 32);
pragma Assert (Val_2'Size = Val'Size * 2);
-- Assert that both are aligned the same, to the size in bytes of Val
-- (not Val_2).
pragma Assert (Val'Alignment = Val'Size / Storage_Unit);
pragma Assert (Val_2'Alignment = Val'Alignment);
type Val_Array is array (Positive range <>) of Val;
-- It might make more sense to have:
-- subtype Val is Val_2 range 0 .. 2**Val'Size - 1;
-- But then GNAT gets the component size of Val_Array wrong.
pragma Assert (Val_Array'Alignment = Val'Alignment);
pragma Assert (Val_Array'Component_Size = Val'Size);
subtype Bit_Size is Natural; -- Size in bits of a bit field
subtype Small_Size is Bit_Size range 1 .. Val'Size;
-- Size of a small one
subtype Bit_Offset is Small_Size'Base range 0 .. Val'Size - 1;
-- Starting offset
subtype Bit_Offset_In_Byte is Bit_Offset range 0 .. Storage_Unit - 1;
procedure Copy_Bitfield
(Src_Address : Address;
Src_Offset : Bit_Offset_In_Byte;
Dest_Address : Address;
Dest_Offset : Bit_Offset_In_Byte;
Size : Bit_Size);
-- An Address and a Bit_Offset together form a "bit address". This
-- copies the source bit field to the destination. Size is the size in
-- bits of the bit field. The bit fields can be arbitrarily large, but
-- the starting offsets must be within the first byte that the Addresses
-- point to. The Address values need not be aligned.
--
-- For example, a slice assignment of a packed bit field:
--
-- D (D_First .. D_Last) := S (S_First .. S_Last);
--
-- can be implemented using:
--
-- Copy_Bitfield
-- (S (S_First)'Address, S (S_First)'Bit,
-- D (D_First)'Address, D (D_First)'Bit,
-- Size);
function Fast_Copy_Bitfield
(Src : Val_2;
Src_Offset : Bit_Offset;
Dest : Val_2;
Dest_Offset : Bit_Offset;
Size : Small_Size)
return Val_2 with Inline;
-- Faster version of Copy_Bitfield, with a different calling convention.
-- In particular, we pass by copy rather than passing Addresses. The bit
-- field must fit in Val_Bits. Src and Dest must be properly aligned.
-- The result is supposed to be assigned back into Dest, as in:
--
-- Dest := Fast_Copy_Bitfield (Src, ..., Dest, ..., ...);
end G;
end System.Bitfield_Utils;