ISO/ IEC JTC1/SC22/WG14 N706

From peren!uunet!dkuug.dk!SC22WG14-request Tue Jun 10 05:36 PDT 1997
Return-Path: <peren!uunet!dkuug.dk!SC22WG14-request>
Received: by cobra. (5.x/SMI-SVR4)
	id AA08074; Tue, 10 Jun 1997 05:36:39 -0700
	id FAA04828; Tue, 10 Jun 1997 05:13:07 -0700
	(peer crosschecked as: dkuug.dk [193.88.44.89])
	id QQcthj12042; Tue, 10 Jun 1997 02:56:54 -0400 (EDT)
Received: from peren by cobra; Tue, 10 Jun 1997 05:36 PDT
Received: by  (SMI-8.6/SMI-SVR4)
	id FAA04828; Tue, 10 Jun 1997 05:13:07 -0700
	(peer crosschecked as: dkuug.dk [193.88.44.89])
	id QQcthj12042; Tue, 10 Jun 1997 02:56:54 -0400 (EDT)
Received: from uunet by peren; Tue, 10 Jun 1997 05:13 PDT
Received: from dkuug.dk by relay7.UU.NET with SMTP 
	(peer crosschecked as: dkuug.dk [193.88.44.89])
	id QQcthj12042; Tue, 10 Jun 1997 02:56:54 -0400 (EDT)
Received: (from daemon@localhost) by dkuug.dk (8.6.12/8.6.12) id IAA00442 for SC22WG14-list; Tue, 10 Jun 1997 08:53:19 +0200
Errors-To: peren!uunet!dkuug.dk!SC22WG14-request
>Received: by  (SMI-8.6/SMI-SVR4)
	id FAA04828; Tue, 10 Jun 1997 05:13:07 -0700
>Received: from dkuug.dk by relay7.UU.NET with SMTP 
	(peer crosschecked as: dkuug.dk [193.88.44.89])
	id QQcthj12042; Tue, 10 Jun 1997 02:56:54 -0400 (EDT)
Message-Id: <199706100653.IAA00442@dkuug.dk>
From: "Jan Kristoffersen" <peren!uunet!pip.dknet.dk!jkristof>
X-Sequence: SC22WG14@dkuug.dk 3750
Errors-To: peren!uunet!dkuug.dk!SC22WG14-request
To: "SC22WG14" <uunet!dkuug.dk!sc22wg14>
Subject: (SC22WG14.3750) N706 Basic I/O hardware adressing as plain text
Date: Tue, 10 Jun 1997 08:48:06 +0200
X-Msmail-Priority: Normal
X-Priority: 3
X-Mailer: Microsoft Internet Mail 4.70.1155
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Type: multipart/mixed; boundary="----=_NextPart_000_01BC757B.03F709C0"
Content-Length: 23617
Status: R

This is a multi-part message in MIME format.

------=_NextPart_000_01BC757B.03F709C0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit


>> Jan Kristoffersen writes:
>>I got the pre-London paper mail today and discovered that the
>>5 last pages are missing from document N706 : Basic I/O >>hardware
addressing, Draft 1.31.
>> The full document N706 is attached to this E-mail. I will also
>> handout new paper copies of N706 monday morning at the
>> London meeting. 
. 
jb writes:
>I had a lot of problems printing you paper.  I needed to change
> the paper size and the paging.  Could you save this paper as a 
> postscript document for 8 1/2 by 11 inch paper?

>Douglas writes:
>Cannot read your attachment.  Can't figure out what it is.  Please
>send postscipt or PDF.

Sorry, none of the editors I have access to can save documents in
postscript format.
Instead I have attached the N706 document as plain text, 
with footnotes made inline. I hope that will do.

Jan
------=_NextPart_000_01BC757B.03F709C0
Content-Type: application/octet-stream; name="N706.txt"
Content-Transfer-Encoding: 7bit
Content-Description: N706.txt (Text Document)
Content-Disposition: attachment; filename="N706.txt"



Document Number: WG14 N706/X3J11 

STANDARDIZATION OF BASIC I/O HARDWARE ADDRESSING.

Title: STANDARDIZATION OF BASIC I/O HARDWARE ADDRESSING.
Author: Jan Kristoffersen
Author Affiliation: RAMTEX International AS
Postal Address: Box 84, 2850 Naerum, Denmark
E-mail Address: jkristof@pip.dknet.dk
Telephone Number: +45 45505357
Fax Number: +45 45505390
Sponsor: DS
Date: May 22, 1997
Proposal Category:
   __ Editorial change/non-normative contribution
   __ Correction
   XX New feature
   __ Addition to obsolescent feature list
   __ Addition to Future Directions
   __ Other (please specify)  
Area of Standard Affected:
   __ Environment
   __ Language
   __ Preprocessor
   XX Library
      __ Macro/typedef/tag name
      XX Function
      XX Header
   XX Other (please specify)  New Annex
______________________________

Prior Art: Widely used
Target Audience: Device driver programmers, I/O chip manufactures

Related Documents (if any):
     WG14 N509/X3J11 95-110     Introduction paper
     WG14 N558/X3J11 95-110     Proposal
     WG14 N656/X3J11            Revised Proposal

-------------------------------

               Annex X (Draft 1.31)
                   (informative)
         Basic I/O hardware addressing <iohw.h>


X.1 Introduction

[1] The header <iohw.h> declares several functions for making
direct access to I/O registers in peripheral hardware. F1

F1  The term peripheral hardware includes, but is not limited to, 
    I/O chips, I/O cells, and I/O circuitry. 
    A peripheral hardware device can be considered as a collection 
    of individual I/O registers.

The purpose of these functions is to make device driver functions
for peripheral I/O hardware more portable between different
execution environments and implementations. F2

F2  I/O driver portability is defined as follows:
    a. If it is possible to reuse I/O hardware with another platform, 
       then it should also be possible to reuse the hardware device 
       drivers for that I/O hardware in the new platform, without any
       modifications to the driver source code.
    b. If there exists two translators for the same platform, it 
       should be possible to compile I/O hardware device driver source
       code with either translators, and get the same logical behaviors
       time of execution.


X.1.1 Conceptual model for I/O registers

[1] A given I/O register is always considered to have a fixed
size in number of bits. This register size is independent of the
execution environment and the implementation.
The I/O functions in <iohw.h> consider an I/O register to belong
to one of the following categories: 1 bit, 8 bit, 16 bit, 32 bit,
or 64 bit.

[2] The I/O functions in <iohw.h> deals with four basic
operations on I/O registers: read, write, bit-wise AND, and
bit-wise OR. F3

F3  AND operations are used for clearing register bits. OR operations
    are used for setting register bits.


[3] I/O registers, or individual bits in a register, are assumed
to belong to one of the categories below. Each category places
different restrictions on allowed operations. F4

F4  As to which access category an given I/O register belongs to 
    depends of the physical characteristics of the register itself
    and its physical location in the execution environment. 


   Register category            Allowed operation
     Read-Only                        Read 
     Write-Only                       Write
     Read-and-Write F5                Read, Write
     Read-Modify-Write F6             Read, Write, AND, OR

F5  Behaves like a read-only register and a write-only register 
    on the same physical address.
F6  Behaves like a memory cell.

The result of an operation not allowed by the register category
shall be considered as undefined.

X.2 Access type parameter

[1] The I/O functions declared in <iohw.h> shall use a single
parameter, the access type, as identification of an I/O register.
The access type parameter represents or references a complete
description of how a given register is connected in the given
hardware platform with the given processor architecture. F7

F7  That is, how the I/O register should be addressed.


[2] Access type parameter definitions shall be included via the
header <iohw.h>. F8

F8  This encapsulates the descriptions of processor and platform
    architecture differences.
    The recommended practice is to let <iohw.h> contain I/O 
    function definitions specific to the processor architecture,
    and let <iohw.h> include a separate header <iohw_ta.h> which
    contain access type definitions for all I/O registers in the
    given target platform.


X.2.1 Access type parameter definitions

[1] The definition of access type parameters will be
implementation defined. F9

F9  An access type definition will typically depend on the given 
    processor architecture, platform hardware, and translator.


[2] A typical implementation will operate with the following five
access type categories, one for each register size: 

      access1
      access8
      access16
      access32
      access64

[3] An I/O register definition shall contain the following
elements:

1.    A symbolic I/O register name

which represents a complete specification of the access method
for the I/O register in the given hardware platform:

2.    I/O register data size: (i.e., 1, 8, 16, 32, or 64 bits)
3.    Address space used (if more than one address space)
4a.   Physical address (if data size = register size)
          or
4b.   Physical address, bit position. (if bit is in a register)
 

X.3 I/O Functions

X.3.1 I/O register read functions

X.3.1.1 The iord1 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      bool iord1( access1 adr );

Description

[2] The iord1 function reads a value from an 1-bit register whose
physical location is defined by the argument adr.

Returns

[3] The iord1 function returns the value read from the 1-bit
register. 

X.3.1.2 The iord8 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      uint_least8_t iord8( access8 adr );

Description

[2] The iord8 function reads a value from an 8-bit register whose
physical location is defined by the argument adr.

Returns

[3] The iord8 function returns the value read from the 8-bit
register. 

X.3.1.3 The iord16 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      uint_least16_t iord16( access16 adr );

Description

[2] The iord16 function reads a value from a 16-bit register
whose physical location is defined by the argument adr.

Returns

[3] The iord16 function returns the value read from the 16-bit
register. 

X.3.1.4 The iord32 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      uint_least32_t iord32( access32 adr );

Description

[2] The iord32 function reads a value from a 32-bit register
whose physical location is defined by the argument adr.

Returns

[3] The iord32 function returns the value read from the 32-bit
register. 

X.3.1.5 The iord64 function

Synopsis
[1]   #include <inttypes.h>
      #include <iohw.h>
      uint_least64_t iord64( access64 adr );

Description

[2] The iord64 function reads a value from a 64-bit register
whose physical location is defined by the argument adr.

Returns

[3] The iord64 function returns the value read from the 64-bit
register. 

X.3.2 I/O register write functions

X.3.2.1 The iowr1 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void iowr1( access1 adr, bool value );

Description

[2] The iowr1 function writes the argument value to a 1-bit
register whose physical location is defined by the argument adr.


X.3.2.2 The iowr8 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void iowr8( access8 adr, uint_least8_t value );

Description

[2] The iowr8 function writes the argument value to an 8-bit
register whose physical location is defined by the argument adr.

X.3.2.3 The iowr16 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void iowr16( access16 adr, uint_least16_t value );

Description

[2] The iowr16 function writes the argument value to a 16-bit
register whose physical location is defined by the argument adr.

X.3.2.4 The iowr32 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void iowr32( access32 adr, uint_least32_t value );

Description

[2] The iowr32 function writes the argument value to a 32-bit
register whose physical location is defined by the argument adr.

X.3.2.5 The iowr64 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void iowr64( access64 adr, uint_least64_t value );

Description

[2] The iowr64 function writes the argument value to a 64-bit
register whose physical location is defined by the argument adr.

X.3.3 I/O register AND functions

X.3.3.1 The ioand1 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void ioand1( access1 adr, bool value );

Description

[2] The ioand1 function performs a bit-wise AND of the argument
value and a 1-bit register whose physical location is defined by
the argument adr. The result of the operation is stored in the
register.

X.3.3.2 The ioand8 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void ioand8( access8 adr, uint_least8_t value );

Description

[2] The ioand8 function performs a bit-wise AND of the argument
value and an 8-bit register whose physical location is defined
by the argument adr. The result of the operation is stored in the
register.

X.3.3.3 The ioand16 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void ioand16( access16 adr, uint_least16_t value );

Description

[2] The ioand16 function performs a bit-wise AND of the argument
value and a 16-bit register whose physical location is defined
by the argument adr. The result of the operation is stored in the
register.

X.3.3.4 The ioand32 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void ioand32( access32 adr, uint_least32_t value );

Description

[2] The ioand32 function performs a bit-wise AND of the argument
value and a 32-bit register whose physical location is defined
by the argument adr. The result of the operation is stored in the
register.

X.3.3.5 The ioand64 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void ioand64( access64 adr, uint_least64_t value );

Description

[2] The ioand64 function performs a bit-wise AND of the argument
value and a 64-bit register whose physical location is defined
by the argument adr. The result of the operation is stored in the
register.

X.3.4 I/O register OR functions

X.3.4.1 The ioor1 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void ioor1( access1 adr, bool value );

Description

[2] The ioor1 function performs a bit-wise OR of the argument
value and a 1-bit register whose physical location is defined by
the argument adr. The result of the operation is stored in the
register.

X.3.4.2 The ioor8 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void ioor8( access8 adr, uint_least8_t value );

Description

[2] The ioor8 function performs a bit-wise OR of the argument
value and an 8-bit register whose physical location is defined
by the argument adr. The result of the operation is stored in the
register.

X.3.4.3 The ioor16 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void ioor16( access16 adr, uint_least16_t value );

Description

[2] The ioor16 function performs a bit-wise OR of the argument
value and a 16-bit register whose physical location is defined
by the argument adr. The result of the operation is stored in the
register.

X.3.4.4 The ioor32 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void ioor32( access32 adr, uint_least32_t value );

Description

[2] The ioor32 function performs a bit-wise OR of the argument
value and a 32-bit register whose physical location is defined
by the argument adr. The result of the operation is stored in the
register.

X.3.4.5 The ioor64 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void ioor64( access64 adr, uint_least64_t value );

Description

[2] The ioor64 function performs a bit-wise OR of the argument
value and a 64-bit register whose physical location is defined
by the argument adr. The result of the operation is stored in the
register.


X.3.5 I/O buffer read functions

X.3.5.1 The iordbuf8 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      uint_least8_t iordbuf8( access8 adr, unsigned int index );

Description

[2] The iordbuf8 function reads the value of the [index] element
in a hardware buffer arranged as a one-dimensional array of 8-bit
registers. The physical location of element [0] is defined by the
argument adr.

Returns

[3] The iordbuf8 function returns the value read from the 8-bit
register. 

X.3.5.2 The iordbuf16 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      uint_least16_t iordbuf16( access16 adr, unsigned int index );

Description

[2] The iordbuf16 function reads the value of the [index] element
in a hardware buffer arranged as a one-dimensional array of
16-bit registers. The physical location of element [0] is defined
by the argument adr.

Returns

[3] The iordbuf16 function returns the value read from the 16-bit
register. 

X.3.5.3 The iordbuf32 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      uint_least32_t iordbuf32( access32 adr, unsigned int index );

Description

[2] The iordbuf32 function reads the value of the [index] element
in a hardware buffer arranged as a one-dimensional array of
32-bit registers. The physical location of element [0] is defined
by the argument adr.

Returns

[3] The iordbuf32 function returns the value read from the 32-bit
register. 

X.3.5.4 The iordbuf64 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      uint_least64_t iordbuf64( access64 adr, unsigned int index );

Description

[2] The iordbuf64 function reads the value of the [index] element
in a hardware buffer arranged as a one-dimensional array of
64-bit registers. The physical location of element [0] is defined
by the argument adr.

Returns

[3] The iordbuf64 function returns the value read from the 64-bit
register. 

X.3.6 I/O buffer write functions

X.3.6.1 The iowrbuf8 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void iowr8( access8 adr, unsigned int index, uint_least8_t value );

Description

[2] The iowrbuf8 function writes value to the [index] element in
a hardware buffer arranged as a one-dimensional array of 8-bit
registers. The physical location of element [0] is defined by the
argument adr.

X.3.6.2 The iowrbuf16 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void iowr16( access16 adr, unsigned int index, uint_least16_t value );

Description

[2] The iowrbuf16 function writes value to the [index] element
in a hardware buffer arranged as a one-dimensional array of
16-bit registers. The physical location of element [0] is defined
by the argument adr.

X.3.6.3 The iowrbuf32 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void iowr32( access32 adr, unsigned int index, uint_least32_t value );

Description

[2] The iowrbuf32 function writes value to the [index] element
in a hardware buffer arranged as a one-dimensional array of
32-bit registers. The physical location of element [0] is defined
by the argument adr.

X.3.6.4 The iowrbuf64 function

Synopsis
[1]
      #include <inttypes.h>
      #include <iohw.h>
      void iowr64( access64 adr, unsigned int index, uint_least64_t value );

Description

[2] The iowrbuf64 function writes value to the [index] element
in a hardware buffer arranged as a one-dimensional array of
64-bit registers. The physical location of element [0] is defined
by the argument adr.


X.3.7 I/O buffer AND functions

X.3.7.1 The ioandbuf8 function

Synopsis
[1]
   #include <inttypes.h>
   #include <iohw.h>
   void ioandbuf8( access8 adr, unsigned int index, uint_least8_t value );

Description

[2] The ioandbuf8 function performs a bit-wise AND of the
argument value and the [index] element in a hardware buffer
arranged as a one-dimensional array of 8-bit registers. The
result of the operation is stored in the [index] register. The
physical location
of element [0] is defined by the argument adr.

X.3.7.2 The ioandbuf16 function

Synopsis
[1]
   #include <inttypes.h>
   #include <iohw.h>
   void ioandbuf16( access16 adr, unsigned int index, uint_least16_t value );

Description

[2] The ioandbuf16 function performs a bit-wise AND of the
argument value and the [index] element in a hardware buffer
arranged as a one-dimensional array of 16-bit registers. The
result of the operation is stored in the [index] register. The
physical location of element [0] is defined by the argument adr.


X.3.7.3 The ioandbuf32 function

Synopsis
[1]
   #include <inttypes.h>
   #include <iohw.h>
   void ioandbuf32( access32 adr, unsigned int index, uint_least32_t value );

Description

[2] The ioandbuf32 function performs a bit-wise AND of the
argument value and the [index] element in a hardware buffer
arranged as a one-dimensional array of 32-bit registers. The
result of the operation is stored in the [index] register. The
physical location of element [0] is defined by the argument adr.

X.3.7.4 The ioandbuf64 function

Synopsis
[1]
   #include <inttypes.h>
   #include <iohw.h>
   void ioandbuf64( access64 adr, unsigned int index, uint_least64_t value );

Description

[2] The ioandbuf64 function performs a bit-wise AND of the
argument value and the [index] element in a hardware buffer
arranged as a one-dimensional array of 64-bit registers. The
result of the operation is stored in the [index] register. The
physical location of element [0] is defined by the argument adr. 

X.3.8 I/O buffer OR functions

X.3.8.1 The ioorbuf8 function

Synopsis
[1]
   #include <inttypes.h>
   #include <iohw.h>
   void ioorbuf8( access8 adr, unsigned int index, uint_least8_t value );

Description

[2] The ioorbuf8 function performs a bit-wise OR of the argument
value and the [index] element in a hardware buffer arranged as
a one-dimensional array of 8-bit registers. The result of the
operation is stored in the [index] register. The physical
location
of element [0] is defined by the argument adr.

X.3.8.2 The ioorbuf16 function

Synopsis
[1]
   #include <inttypes.h>
   #include <iohw.h>
   void ioorbuf16( access16 adr, unsigned int index, uint_least16_t value );

Description

[2] The ioorbuf16 function performs a bit-wise OR of the argument
value and the [index] element in a hardware buffer arranged as
a one-dimensional array of 16-bit registers. The result of the
operation is stored in the [index] register. The physical
location
of element [0] is defined by the argument adr.

X.3.8.3 The ioorbuf32 function

Synopsis
[1]
   #include <inttypes.h>
   #include <iohw.h>
   void ioorbuf32( access32 adr, unsigned int index, uint_least32_t value );

Description

[2] The ioorbuf32 function performs a bit-wise OR of the argument
value and the [index] element in a hardware buffer arranged as
a one-dimensional array of 32-bit registers. The result of the
operation is stored in the [index] register. The physical
location
of element [0] is defined by the argument adr.

X.3.8.4 The ioorbuf64 function

Synopsis
[1]
   #include <inttypes.h>
   #include <iohw.h>
   void ioorbuf64( access64 adr, unsigned int index, uint_least64_t value );

Description

[2] The ioorbuf64 function performs a bit-wise OR of the argument
value and the [index] element in a hardware buffer arranged as
a one-dimensional array of 64-bit registers. The result of the
operation is stored in the [index] register. The physical
location
of element [0] is defined by the argument adr.

X.3.9 I/O function implementation

[1] A conforming implementation may support an execution
environment in which one or more of the functions described above
cannot be implemented. F10

F10  A typical implementation is not expected to have I/O functions
     for register sizes larger than what is supported by the 
     processor architecture. 

[2] A conforming implementation may support an execution
environment in which the access type parameter adr in one or more
of the functions above cannot be used as a variable. F11

F11  Some processor architectures may require that the access type
     parameter is defined as a constant at compile time.

[3] A conforming implementation may implement the above functions
as macros. F12

F12  An implementation can used macros in stead of functions in
     order to generate efficient in-line code.

[4] An I/O function implementation should not handle limitations
which originate from limitations in the physical I/O hardware. F13

F13  The purpose of the I/O functions is to hide processor 
     architecture differences, not the characteristics of the I/O
     hardware.



Example
AND and OR operations are not permitted on the register types
write-only and read-only. Such limitations, which originate from
the physical I/O hardware registers, should not be handled nor
masked by an implementation of the I/O functions. The handling
of such limitations should be done by the driver function not the
I/O functions.


X.4 Constraints

X.4.1 Atomic operations

[1] The I/O functions do not guarantee that read-modify-write
operations will be atomic.

Example:

[2] For some processor types the statement:

   ioand8( PORT3, 0xf3 );

may be implemented as separate machine operations; for example:

   in temp,PORT3; 
   and temp,0xf3; 
   out PORT3,temp;

X.4.2 Compiler optimization

[1] The I/O functions do not guarantee two ioxxxx operations will
always be two separate operations. Two operations in a statement
are allowed to be combined to a single read-modify-write
operation by the translator. 

Example:

[2] The statement:

   iowr8(PORT1, iord8(PORT1) + 0x10);

can be optimized by the translator to a single machine
instruction; for example:

   ADD   PORT1,0x10


------=_NextPart_000_01BC757B.03F709C0--