Lines Matching +full:write +full:- +full:to +full:- +full:read

15 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29 .\" This code is derived from software contributed to The NetBSD Foundation
43 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
46 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
626 functions exist to allow device drivers
627 machine-independent access to bus memory and register areas.
639 limitations might change the way registers need to be accessed (e.g.\&
640 creating a non-linear register space).
642 driver may need to access the same type of device in multiple ways in a
646 functions is to allow a single driver source file to manipulate a set
647 of devices on different system architectures, and to allow a single driver
648 object file to manipulate a set of devices on multiple bus types on a
651 Not all buses have to implement all functions described in this
655 compile-time errors if possible.
658 function prototypes and discussed as if they were required to be
660 Implementations are encouraged to implement prototyped
661 (type-checked) versions of these interfaces, but may implement them as
663 Machine-dependent types, variables, and functions
667 machine-independent types and functions, and, if possible, should be
668 given names which make the machine-dependence clear.
671 machine-dependent code.
693 Access to regions of bus space is facilitated by use of bus space handles,
705 actual location(s) to be accessed.
708 The offset used to access data
709 relative to a given handle must be such that all of the data being
711 Trying to
714 Because some architectures' memory systems use buffering to improve
716 used to create
718 in the bus space read and write stream.
720 are three types of barriers: read, write, and read/write.
722 started to the region before a read barrier must complete before any reads
723 after the read barrier are started.
725 write barriers.)
726 Read/write barriers force all reads and writes started
727 before the barrier to complete before any reads or writes after the
729 Correctly-written drivers will include all
730 appropriate barriers, and assume only the read/write ordering imposed by
733 People trying to write portable drivers with the
736 try to make minimal assumptions about what the system allows.
739 accessed to be naturally aligned (i.e., base address of handle added to
741 alignment checking on pointers (i.e., pointer to objects being read and
742 written must point to properly-aligned data).
749 or arguments that are out of range (e.g.\& trying to access data outside of
753 system to halt, either intentionally (via panic) or unintentionally (by
758 or which return data read from bus space (i.e., functions which
774 type is used to describe bus addresses.
783 type is used to describe sizes of ranges in bus space.
795 type is used to describe a particular bus space on a machine.
797 contents are machine-dependent and should be considered opaque by
798 machine-independent code.
801 functions to name the space on which they are operating.
805 type is used to describe a mapping of a range of bus space.
807 contents are machine-dependent and should be considered opaque by
808 machine-independent code.
812 This section is specific to the
814 version of these functions and may or may not apply to the
826 Some drivers need to be able to pass a subregion of already-mapped bus
827 space to another driver or module within a driver.
830 function allows such subregions to be created.
840 and fills in the bus space handle pointed to by
843 that can be used to access the mapped region.
845 it will return non-zero and leave the bus space handle pointed
852 argument controls how the space is to be mapped.
854 .Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE"
856 Try to map the space so that accesses can be cached and/or
865 Try to map the space so that its contents can be accessed linearly via
868 This is useful when software wants to do direct access to a memory
878 Try to map the space using non-posted device memory.
879 This is to support buses and devices where mapping with posted device
894 When the system hardware or firmware provides hints as to how spaces should be
901 non-cacheable mapping when the system can only provide a cacheable one)
902 will cause the request to fail.
905 bus spaces and refuse to allow duplicate allocations.
907 for bus spaces which have no notion of slot-specific space addressing,
909 (e.g.\& PCI memory and I/O spaces co-existing with ISA memory and
915 bus-dependent.
924 the same as the size given to
946 new handle to some subregion of an already-mapped region of bus space.
958 space handle pointed to by
960 If unsuccessful, it returns non-zero and leaves the bus space handle
961 pointed to by
984 This section is specific to the
986 version of these functions and may or may not apply to the
990 Some devices require or allow bus space to be allocated by the operating
1005 corresponding to the given constraints.
1007 zero, fills in the bus address pointed to by
1010 the bus space handle pointed to by
1012 with the handle that can be used to access that region.
1013 If unsuccessful, it returns non-zero and leaves the bus address pointed to by
1015 and the bus space handle pointed to by
1034 constraint, if non-zero, ensures that the region is allocated so that
1045 It is an error to specify a set of
1054 parameter is the same as the like-named parameter to
1063 Trying to use
1079 specified should be the same as the size given to
1097 The simplest way to access bus space is to read or write a single data
1104 the ability to read and write 1, 2, 4, and 8 byte data items on buses
1119 The location being read must lie within the bus space region specified by
1124 plus the offset should be a multiple of the size of data item being read.
1125 On some systems, not obeying this requirement may cause incorrect data to
1126 be read, on others it may cause a system crash.
1128 Read operations done by the
1131 of order with respect to other pending read and write operations unless
1147 family of functions writes a 1, 2, 4, or 8 byte data item to the offset
1163 incorrect data to be written, on others it may cause a system crash.
1165 Write operations done by the
1168 out of order with respect to other pending read and write operations
1185 device responds to the read or write cycles.
1186 In such a situation, the system typically would panic due to a kernel-mode
1192 family of functions provide a mechanism to handle these exceptions
1199 the peek and poke functions provide the ability to read and
1200 write 1, 2, 4, and 8 byte data items on busses which support those
1206 functions also apply to
1211 In addition, explicit calls to the
1220 responding to the operation at the specified offset in the bus space.
1221 A non-zero return value indicates that the kernel intercepted a
1225 non-existent hardware is accessed.
1227 the data read by
1235 functions are not re-entrant and should not, therefore, be used
1239 .Bl -ohang -compact
1247 family of functions cautiously read a 1, 2, 4, or 8 byte data item from
1254 The data item read is stored in the location pointed to by
1258 to be NULL, in which case the data item will be discarded after being read.
1267 family of functions cautiously write a 1, 2, 4, or 8 byte data item
1278 In order to allow high-performance buffering implementations to avoid bus
1279 activity on every operation, read and write ordering should be specified
1287 function enforces ordering of bus space read and write operations
1299 argument controls what types of operations are to be ordered.
1301 .Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE"
1303 Synchronize read operations.
1305 Synchronize write operations.
1308 Those flags can be combined (or-ed together) to enforce ordering on both
1309 read and write operations.
1311 All of the specified type(s) of operation which are done to the region
1312 before the barrier operation are guaranteed to complete before any of the
1315 Example: Consider a hypothetical device with two single-byte ports, one
1316 write-only input port (at offset 0) and a read-only output port (at
1320 which is read by reading from the output port.
1321 The sequence to correctly
1322 write two data bytes to the device then read those two data bytes back
1324 .Bd -literal
1340 The first barrier makes sure that the first write finishes before the
1341 second write is issued, so that two writes to the input port are done
1342 in order and are not collapsed into a single write.
1344 the data bytes are written to the device correctly and in order.
1346 The second barrier makes sure that the writes to the output port finish
1347 before any of the reads to the input port are issued, thereby making sure
1348 that all of the writes are finished before data is read.
1350 that the first byte read from the device really is the last one that was
1353 The third barrier makes sure that the first read finishes before the
1354 second read is issued, ensuring that data is read correctly and in order.
1356 The barriers in the example above are specified to cover the absolute
1359 easier) to make barrier operations cover the device's whole range of bus
1360 space, that is, to specify an offset of zero and the size of the
1364 Often, drivers want to copy the contents of those buffers to or from
1365 memory, e.g.\& into mbufs which can be passed to higher levels of the
1366 system or from mbufs to be output to a network.
1367 In order to allow
1368 drivers to do this as efficiently as possible, the
1374 Drivers occasionally need to copy one region of a bus space to another,
1375 or to set all locations in a region of bus space to contain a single
1381 family of functions allow drivers to perform these operations.
1399 Each successive data item is read from an offset
1402 All locations being read must lie within the bus
1409 read and the data array pointer should be properly aligned.
1411 systems, not obeying these requirements may cause incorrect data to be
1412 read, on others it may cause a system crash.
1414 Read operations done by the
1418 of order with respect to other pending read and write operations unless
1422 There is no way to insert barriers between reads of
1443 and writes them to bus space starting at byte offset
1450 Each successive data item is written to an offset 1, 2, 4,
1462 systems, not obeying these requirements may cause incorrect data to be
1465 Write operations done by the
1470 respect to other pending read and write operations unless order is
1474 There is no way to insert barriers between writes of
1508 Each successive data item read or written has
1511 All locations being read and written must
1518 requirement may cause incorrect data to be copied, on others it may cause
1521 Read and write operations done by the
1525 of order with respect to other pending read and write operations unless
1529 There is no way to insert barriers between reads or writes of
1573 incorrect data to be written, on others it may cause a system crash.
1575 Write operations done by the
1580 respect to other pending read and write operations unless order is
1584 There is no way to insert barriers between writes of
1595 Some devices implement single locations in bus space which are to be read
1596 or written multiple times to communicate data, e.g.\& some ethernet
1598 In order to allow drivers to manipulate
1622 Each successive data item is read from the same location in bus
1624 The location being read must lie within the bus space region
1631 read and the data array pointer should be properly aligned.
1633 systems, not obeying these requirements may cause incorrect data to be
1634 read, on others it may cause a system crash.
1636 Read operations done by the
1639 executed out of order with respect to other pending read and write
1645 functions read the same bus space location multiple times, they
1646 place an implicit read barrier between each successive read of that bus
1671 Each successive data item is written to the same location in
1682 systems, not obeying these requirements may cause incorrect data to be
1685 Write operations done by the
1687 functions may be executed out of order with respect to other pending
1688 read and write operations unless order is enforced by use of the
1693 functions write the same bus space location multiple times, they
1694 place an implicit write barrier between each successive write of that
1727 systems, not obeying these requirements may cause incorrect data to be
1730 Write operations done by the
1732 functions may be executed out of order with respect to other pending
1733 read and write operations unless order is enforced by use of the
1738 functions write the same bus space location multiple times, they
1739 place an implicit write barrier between each successive write of that
1750 functions imply a host byte-order and a bus byte-order and take care of
1753 for which the caller may want to use multi-word, yet untranslated access.
1754 Access to these types of memory regions should be with the
1758 .Bl -tag -compact -width Fn
1797 These functions are defined just as their non-stream counterparts,
1798 except that they provide no byte-order translation.
1818 The functions were merged to work on generic
1822 development cycle, and many drivers were converted to use them.
1825 development cycle, and the specification was updated to fix some
1826 consistency problems and to add some missing functionality.
1828 The manual page was then adapted to the version of the interface that
1837 .An -nosplit
1854 ported these interfaces to