share/man/man4/altera_avgen.4

   1 .\"-
   2 .\" Copyright (c) 2012 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed by SRI International and the University of
   6 .\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237)
   7 .\" ("CTSRD"), as part of the DARPA CRASH research programme.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd August 18, 2012
  33 .Dt ALTERA_AVGEN 4
  34 .Os
  35 .Sh NAME
  36 .Nm altera_avgen
  37 .Nd driver for generic Altera Avalon-bus-attached, memory-mapped devices
  38 .Sh SYNOPSIS
  39 .Cd "device altera_avgen"
  40 .Pp
  41 In
  42 .Pa /boot/device.hints :
  43 .Cd hint.altera_avgen.0.at="nexus0"
  44 .Cd hint.altera_avgen.0.maddr=0x7f00a000
  45 .Cd hint.altera_avgen.0.msize=20
  46 .Cd hint.altera_avgen.0.width=4
  47 .Cd hint.altera_avgen.0.fileio="rw"
  48 .Cd hint.altera_avgen.0.devname="berirom"
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 device driver provides generic support for memory-mapped devices on the
  53 Altera Avalon bus.
  54 .Pa device.hints
  55 entries configure the address, size, I/O disposition, and
  56 .Pa /dev
  57 device node name that will be used.
  58 The
  59 .Xr open 2 ,
  60 .Xr read 2 ,
  61 .Xr write 2 ,
  62 and
  63 .Xr mmap 2
  64 system calls (and variations) may be used on
  65 .Nm
  66 device nodes, subject to constraints imposed using
  67 .Pa device.hints
  68 entries.
  69 Although reading and writing mapped memory is supported,
  70 .Nm
  71 does not currently support directing device interrupts to userspace.
  72 .Pp
  73 A number of
  74 .Pa device.hints
  75 sub-fields are available to configure
  76 .Nm
  77 device instances:
  78 .Bl -tag -width devunit
  79 .It maddr
  80 base physical address of the memory region to export; must be aligned to
  81 .Li width
  82 .It msize
  83 length of the memory region export; must be aligned to
  84 .Li width
  85 .It width
  86 Granularity at which
  87 .Xr read 2
  88 and
  89 .Xr write 2
  90 operations will be performed.
  91 Larger requests will be broken down into
  92 .Li width -sized
  93 operations; smaller requests will be rejected.
  94 I/O operations must be aligned to
  95 .Li width .
  96 .It fileio
  97 allowed file descriptor operations;
  98 .Li r
  99 authorizes
 100 .Xr read 2 ;
 101 .Li w
 102 authorizes
 103 .Xr write 2 .
 104 .It mmapio
 105 allowed
 106 .Xr mmap 2
 107 permissions;
 108 .Li w
 109 authorizes
 110 .Dv PROT_WRITE ;
 111 .Li r
 112 authorizes
 113 .Dv PROT_READ ;
 114 .Li x
 115 authorizes
 116 .Dv PROT_EXEC .
 117 .It devname
 118 specifies a device name relative to
 119 .Pa /dev .
 120 .It devunit
 121 specifies a device unit number; no unit number is used if this is unspecified.
 122 .El
 123 .Sh SEE ALSO
 124 .Xr mmap 2 ,
 125 .Xr open 2 ,
 126 .Xr read 2 ,
 127 .Xr write 2
 128 .Sh HISTORY
 129 The
 130 .Nm
 131 device driver first appeared in
 132 .Fx 10.0 .
 133 .Sh AUTHORS
 134 The
 135 .Nm
 136 device driver and this manual page were
 137 developed by SRI International and the University of Cambridge Computer
 138 Laboratory under DARPA/AFRL contract
 139 .Pq FA8750-10-C-0237
 140 .Pq Do CTSRD Dc ,
 141 as part of the DARPA CRASH research programme.
 142 This device driver was written by
 143 .An Robert N. M. Watson .
 144 .Sh BUGS
 145 .Nm
 146 is intended to support the writing of userspace device drivers; however, it
 147 does not permit directing interrupts to userspace, only memory-mapped I/O.
 148 .Pp
 149 .Nm
 150 supports only a
 151 .Li nexus
 152 bus attachment, which is appropriate for system-on-chip busses such as
 153 Altera's Avalon bus.
 154 If the target device is off of another bus type, then additional bus
 155 attachments will be required.