Index Index for
Section 9
Index Alphabetical
listing for R
Bottom of page Bottom of
page		 

READ_BUS_D8(9r)


NAME

  READ_BUS_D8, READ_BUS_D16, READ_BUS_D32, READ_BUS_D64 - General: Perform
  byte, word, longword, and quadword bus I/O read operations


SYNOPSIS

  unsigned char READ_BUS_D8(
	  io_handle_t dev_addr );

  unsigned short READ_BUS_D16(
	  io_handle_t dev_addr );

  unsigned int READ_BUS_D32(
	  io_handle_t dev_addr );

  unsigned int READ_BUS_D64(
	  io_handle_t dev_addr );


ARGUMENTS

  dev_addr
      Specifies an I/O handle that you can use to reference a device register
      or memory located in bus address space (either I/O space or memory
      space). This I/O handle references a device register in the bus address
      space where the read operation originates. You can perform standard C
      mathematical operations (addition and subtraction only) on the I/O
      handle.


DESCRIPTION

  The READ_BUS_D8 macro reads a byte (8 bits) from a device register located
  in the bus I/O  address space. The READ_BUS_D16 macro reads a word (16
  bits) from a device register located in the bus I/O address space. The
  READ_BUS_D32 macro reads a longword (32 bits) from a device register
  located in the bus I/O address space. The READ_BUS_D64 macro reads a
  quadword (64 bits) from a device register located in the bus I/O address
  space. These are convenience macros that call read_io_port, which is a
  generic routine that maps to a bus- and machine-specific routine that
  actually performs the task of reading the byte, word, longword, or
  quadword. Use of these macros to read data from a device register makes the
  device driver more portable across different bus architectures, different
  CPU architectures, and different CPU types within the same CPU
  architecture.

  In addition to dev_addr, the READ_BUS_D8, READ_BUS_D16, READ_BUS_D32, and
  READ_BUS_D64 macros automatically pass values to the width and flags
  arguments of read_io_port. The following list identifies these values:

    ·  The READ_BUS_D8, READ_BUS_D16, READ_BUS_D32, and READ_BUS_D64 macros
       set the width to the values 1, 2, 4, and 8, respectively.

    ·  The READ_BUS_D8, READ_BUS_D16, READ_BUS_D32, and READ_BUS_D64 macros
       set the flags argument to the value zero (0).







CAUTIONS

  The I/O handle that you pass to the dev_addr argument of the READ_BUS_D8,
  READ_BUS_D16, READ_BUS_D32, and READ_BUS_D64 macros must be an I/O handle
  that references addresses residing in sparse space. All Alpha CPUs support
  sparse space. As a result, all bus configuration code should supply an I/O
  handle that references bus address space.

  If you pass an I/O handle to the dev_addr argument that references
  addresses residing in some other space (for example, dense space) the
  results of the read operation are unpredictable.

  Tru64 UNIX provides the following routines that allow device drivers to
  perform copy operations and zero blocks of memory on addresses that reside
  in dense space:

    ·  bcopy

       Copies a series of bytes with a specified limit

    ·  blkclr and bzero

       Zeros a block of memory

    ·  copyin

       Copies data from a user address space to a kernel address space

    ·  copyinstr

       Copies a null-terminated string from a user address space to a kernel
       address space

    ·  copyout

       Copies data from a kernel address space to a user address space

    ·  copyoutstr

       Copies a null-terminated string from a kernel address space to a user
       address space

  The read_io_port and write_io_port routines (and by extension, the macros
  built from these routines) do not support unaligned data accesses that
  cross longword boundaries.  You can access unaligned data by providing an
  macro that checks the lower bits of an I/O address to determine the byte
  boundary of the I/O read or write operation to be performed and the width
  of the data to be read or written. If an alignment problem exists, you can
  break up the read or write operation into separate byte-size reads or
  writes.

  The READ_DEVICECSR_USHORT example macro reads an unsigned word of data from
  a device register. The READ_DEVICECSR_USHORT macro is called instead of
  directly calling the READ_BUS_D16 macro.  The READ_DEVICECSR_USHORT macro
  first masks out the lower 2 bits of the base address. If the lower 2 bits
  are both high (indicating an address on a tribyte boundary), the driver
  must break up the read operation into 2-byte read operations. The driver
  must also perform appropriate bit-shifting operations to read high and low
  bytes that are then ORed together.

       #define READ_DEVICECSR_USHORT(a)
       (
	(u_short)(
	  (((u_short)(a)&3) == 3)
       /*
	  (((u_short)(a)&1) == 1)  This can be used in drivers with 16-bit
				   CSRs to check if a word read operation
				   crosses a 16-bit register boundary.
       */
	 ?
		 ( (READ_BUS_D8( (io_handle_t)sc->regbase + (a)+1) <<< 8)
		   | READ_BUS_D8( (io_handle_t)sc->regbase + (a) )
		 )
	 :
		 ( READ_BUS_D16((io_handle_t)sc->regbase + (a))
		 );
       )


RETURN VALUES

  Upon successful completion, these macros return the requested data from the
  device register located in the bus address space: READ_BUS_D8 returns a
  byte (8 bits), READ_BUS_D16 returns a word (16 bits), READ_BUS_D32 returns
  a longword (32 bits), and READ_BUS_D64 returns a quadword (64 bits).


SEE ALSO

  Kernel Routines: read_io_port(9r)

Index Index for
Section 9
Index Alphabetical
listing for R
Top of page Top of
page