diff options
Diffstat (limited to 'static/netbsd/man9/bus_space.9 3.html')
| -rw-r--r-- | static/netbsd/man9/bus_space.9 3.html | 2110 |
1 files changed, 0 insertions, 2110 deletions
diff --git a/static/netbsd/man9/bus_space.9 3.html b/static/netbsd/man9/bus_space.9 3.html deleted file mode 100644 index 71ce652b..00000000 --- a/static/netbsd/man9/bus_space.9 3.html +++ /dev/null @@ -1,2110 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">BUS_SPACE(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">BUS_SPACE(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">bus_space</code>, - <code class="Nm">bus_space_barrier</code>, - <code class="Nm">bus_space_copy_region_1</code>, - <code class="Nm">bus_space_copy_region_2</code>, - <code class="Nm">bus_space_copy_region_4</code>, - <code class="Nm">bus_space_copy_region_8</code>, - <code class="Nm">bus_space_free</code>, - <code class="Nm">bus_space_handle_is_equal</code>, - <code class="Nm">bus_space_is_equal</code>, - <code class="Nm">bus_space_map</code>, - <code class="Nm">bus_space_mmap</code>, - <code class="Nm">bus_space_peek_1</code>, - <code class="Nm">bus_space_peek_2</code>, - <code class="Nm">bus_space_peek_4</code>, - <code class="Nm">bus_space_peek_8</code>, - <code class="Nm">bus_space_poke_1</code>, - <code class="Nm">bus_space_poke_2</code>, - <code class="Nm">bus_space_poke_4</code>, - <code class="Nm">bus_space_poke_8</code>, - <code class="Nm">bus_space_read_1</code>, - <code class="Nm">bus_space_read_2</code>, - <code class="Nm">bus_space_read_4</code>, - <code class="Nm">bus_space_read_8</code>, - <code class="Nm">bus_space_read_multi_1</code>, - <code class="Nm">bus_space_read_multi_2</code>, - <code class="Nm">bus_space_read_multi_4</code>, - <code class="Nm">bus_space_read_multi_8</code>, - <code class="Nm">bus_space_read_multi_stream_1</code>, - <code class="Nm">bus_space_read_multi_stream_2</code>, - <code class="Nm">bus_space_read_multi_stream_4</code>, - <code class="Nm">bus_space_read_multi_stream_8</code>, - <code class="Nm">bus_space_read_region_1</code>, - <code class="Nm">bus_space_read_region_2</code>, - <code class="Nm">bus_space_read_region_4</code>, - <code class="Nm">bus_space_read_region_8</code>, - <code class="Nm">bus_space_read_region_stream_1</code>, - <code class="Nm">bus_space_read_region_stream_2</code>, - <code class="Nm">bus_space_read_region_stream_4</code>, - <code class="Nm">bus_space_read_region_stream_8</code>, - <code class="Nm">bus_space_read_stream_1</code>, - <code class="Nm">bus_space_read_stream_2</code>, - <code class="Nm">bus_space_read_stream_4</code>, - <code class="Nm">bus_space_read_stream_8</code>, - <code class="Nm">bus_space_release</code>, - <code class="Nm">bus_space_reservation_addr</code>, - <code class="Nm">bus_space_reservation_init</code>, - <code class="Nm">bus_space_reservation_size</code>, - <code class="Nm">bus_space_reservation_map</code>, - <code class="Nm">bus_space_reservation_unmap</code>, - <code class="Nm">bus_space_reserve</code>, - <code class="Nm">bus_space_reserve_subregion</code>, - <code class="Nm">bus_space_set_region_1</code>, - <code class="Nm">bus_space_set_region_2</code>, - <code class="Nm">bus_space_set_region_4</code>, - <code class="Nm">bus_space_set_region_8</code>, - <code class="Nm">bus_space_subregion</code>, - <code class="Nm">bus_space_tag_create</code>, - <code class="Nm">bus_space_tag_destroy</code>, - <code class="Nm">bus_space_unmap</code>, - <code class="Nm">bus_space_vaddr</code>, - <code class="Nm">bus_space_write_1</code>, - <code class="Nm">bus_space_write_2</code>, - <code class="Nm">bus_space_write_4</code>, - <code class="Nm">bus_space_write_8</code>, - <code class="Nm">bus_space_write_multi_1</code>, - <code class="Nm">bus_space_write_multi_2</code>, - <code class="Nm">bus_space_write_multi_4</code>, - <code class="Nm">bus_space_write_multi_8</code>, - <code class="Nm">bus_space_write_multi_stream_1</code>, - <code class="Nm">bus_space_write_multi_stream_2</code>, - <code class="Nm">bus_space_write_multi_stream_4</code>, - <code class="Nm">bus_space_write_multi_stream_8</code>, - <code class="Nm">bus_space_write_region_1</code>, - <code class="Nm">bus_space_write_region_2</code>, - <code class="Nm">bus_space_write_region_4</code>, - <code class="Nm">bus_space_write_region_8</code>, - <code class="Nm">bus_space_write_region_stream_1</code>, - <code class="Nm">bus_space_write_region_stream_2</code>, - <code class="Nm">bus_space_write_region_stream_4</code>, - <code class="Nm">bus_space_write_region_stream_8</code>, - <code class="Nm">bus_space_write_stream_1</code>, - <code class="Nm">bus_space_write_stream_2</code>, - <code class="Nm">bus_space_write_stream_4</code>, - <code class="Nm">bus_space_write_stream_8</code> — - <span class="Nd">bus space manipulation functions</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/bus.h</a>></code></p> -<p class="Pp"><var class="Ft">bool</var> - <br/> - <code class="Fn">bus_space_handle_is_equal</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle1</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle2</var>);</p> -<p class="Pp"><var class="Ft">bool</var> - <br/> - <code class="Fn">bus_space_is_equal</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space1</var>, <var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space2</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_release</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - t</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_reservation_t - *bsr</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_reserve</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - t</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t bpa</var>, - <var class="Fa" style="white-space: nowrap;">bus_size_t size</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_reservation_t - *bsrp</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_reserve_subregion</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - t</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t - reg_start</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t - reg_end</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - size</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - alignment</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - boundary</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_reservation_t - *bsrp</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_reservation_init</code>(<var class="Fa" style="white-space: nowrap;">bus_space_reservation_t - *bsr</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t - addr</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - size</var>);</p> -<p class="Pp"><var class="Ft">bus_size_t</var> - <br/> - <code class="Fn">bus_space_reservation_size</code>(<var class="Fa" style="white-space: nowrap;">bus_space_reservation_t - *bsr</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_reservation_map</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - t</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_reservation_t - *bsr</var>, <var class="Fa" style="white-space: nowrap;">int flags</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - *bshp</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_reservation_unmap</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - t</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - bsh</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - size</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_map</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t - address</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - size</var>, <var class="Fa" style="white-space: nowrap;">int flags</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - *handlep</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_unmap</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - size</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_subregion</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - size</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - *nhandlep</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_alloc</code>(<var class="Fa">bus_space_tag_t - space</var>, <var class="Fa">bus_addr_t reg_start</var>, - <var class="Fa">bus_addr_t reg_end</var>, <var class="Fa">bus_size_t - size</var>, <var class="Fa">bus_size_t alignment</var>, - <var class="Fa">bus_size_t boundary</var>, <var class="Fa">int flags</var>, - <var class="Fa">bus_addr_t *addrp</var>, <var class="Fa">bus_space_handle_t - *handlep</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_free</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - size</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">bus_space_vaddr</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>);</p> -<p class="Pp"><var class="Ft">paddr_t</var> - <br/> - <code class="Fn">bus_space_mmap</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t - addr</var>, <var class="Fa" style="white-space: nowrap;">off_t off</var>, - <var class="Fa" style="white-space: nowrap;">int prot</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_tag_create</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - obst</var>, <var class="Fa" style="white-space: nowrap;">uint64_t - present</var>, <var class="Fa" style="white-space: nowrap;">uint64_t - extpresent</var>, <var class="Fa" style="white-space: nowrap;">const struct - bus_space_overrides *ov</var>, - <var class="Fa" style="white-space: nowrap;">void *ctx</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_tag_t - *bstp</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_tag_destroy</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - bst</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_peek_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t - *datap</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_peek_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t - *datap</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_peek_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t - *datap</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_peek_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t - *datap</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_poke_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t - data</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_poke_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t - data</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_poke_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t - data</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">bus_space_poke_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t - data</var>);</p> -<p class="Pp"><var class="Ft">uint8_t</var> - <br/> - <code class="Fn">bus_space_read_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>);</p> -<p class="Pp"><var class="Ft">uint16_t</var> - <br/> - <code class="Fn">bus_space_read_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>);</p> -<p class="Pp"><var class="Ft">uint32_t</var> - <br/> - <code class="Fn">bus_space_read_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>);</p> -<p class="Pp"><var class="Ft">uint64_t</var> - <br/> - <code class="Fn">bus_space_read_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t - value</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t - value</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t - value</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t - value</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_barrier</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - length</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_region_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_region_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_region_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_region_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_region_stream_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_region_stream_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_region_stream_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_region_stream_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_region_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint8_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_region_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint16_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_region_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint32_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_region_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint64_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_region_stream_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint8_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_region_stream_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint16_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_region_stream_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint32_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_region_stream_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint64_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_copy_region_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - srchandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - srcoffset</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - dsthandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - dstoffset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_copy_region_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - srchandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - srcoffset</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - dsthandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - dstoffset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_copy_region_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - srchandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - srcoffset</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - dsthandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - dstoffset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_copy_region_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - srchandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - srcoffset</var>, - <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - dsthandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - dstoffset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_set_region_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t - value</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_set_region_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t - value</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_set_region_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t - value</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_set_region_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t - value</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_multi_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_multi_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_multi_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_multi_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_multi_stream_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_multi_stream_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_multi_stream_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_read_multi_stream_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_multi_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint8_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_multi_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint16_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_multi_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint32_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_multi_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint64_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_multi_stream_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint8_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_multi_stream_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint16_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_multi_stream_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint32_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">bus_space_write_multi_stream_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t - space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t - handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - offset</var>, <var class="Fa" style="white-space: nowrap;">const uint64_t - *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t - count</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">bus_space</code> functions exist to allow - device drivers machine-independent access to bus memory and register areas. - All of the functions and types described in this document can be used by - including the <code class="In"><<a class="In">sys/bus.h</a>></code> - header file.</p> -<p class="Pp">Many common devices are used on multiple architectures, but are - accessed differently on each because of architectural constraints. For - instance, a device which is mapped in one system's I/O space may be mapped - in memory space on a second system. On a third system, architectural - limitations might change the way registers need to be accessed (e.g., - creating a non-linear register space). In some cases, a single driver may - need to access the same type of device in multiple ways in a single system - or architecture. The goal of the <code class="Nm">bus_space</code> functions - is to allow a single driver source file to manipulate a set of devices on - different system architectures, and to allow a single driver object file to - manipulate a set of devices on multiple bus types on a single - architecture.</p> -<p class="Pp">Not all busses have to implement all functions described in this - document, though that is encouraged if the operations are logically - supported by the bus. Unimplemented functions should cause compile-time - errors if possible.</p> -<p class="Pp">All of the interface definitions described in this document are - shown as function prototypes and discussed as if they were required to be - functions. Implementations are encouraged to implement prototyped - (type-checked) versions of these interfaces, but may implement them as - macros if appropriate. Machine-dependent types, variables, and functions - should be marked clearly in - <code class="In"><<a class="In">machine/bus_defs.h</a>></code> and in - <code class="In"><<a class="In">machine/bus_funcs.h</a>></code> to - avoid confusion with the machine-independent types and functions, and, if - possible, should be given names which make the machine-dependence clear.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="CONCEPTS_AND_GUIDELINES"><a class="permalink" href="#CONCEPTS_AND_GUIDELINES">CONCEPTS - AND GUIDELINES</a></h1> -<p class="Pp">Bus spaces are described by bus space tags, which can be created - only by machine-dependent code. A given machine may have several different - types of bus space (e.g., memory space and I/O space), and thus may provide - multiple different bus space tags. Individual busses or devices on a machine - may use more than one bus space tag. For instance, ISA devices are given an - ISA memory space tag and an ISA I/O space tag. Architectures may have - several different tags which represent the same type of space, for instance - because of multiple different host bus interface chipsets.</p> -<p class="Pp">A range in bus space is described by a bus address and a bus size. - The bus address describes the start of the range in bus space. The bus size - describes the size of the range in bytes. Busses which are not byte - addressable may require use of bus space ranges with appropriately aligned - addresses and properly rounded sizes.</p> -<p class="Pp">Access to regions of bus space is facilitated by use of bus space - handles, which are usually created by mapping a specific range of a bus - space. Handles may also be created by allocating and mapping a range of bus - space, the actual location of which is picked by the implementation within - bounds specified by the caller of the allocation function.</p> -<p class="Pp">All of the bus space access functions require one bus space tag - argument, at least one handle argument, and at least one offset argument (a - bus size). The bus space tag specifies the space, each handle specifies a - region in the space, and each offset specifies the offset into the region of - the actual location(s) to be accessed. Offsets are given in bytes, though - busses may impose alignment constraints. The offset used to access data - relative to a given handle must be such that all of the data being accessed - is in the mapped region that the handle describes. Trying to access data - outside that region is an error.</p> -<p class="Pp" id="bus_space_barrier">Bus space I/O operations on mappings made - with <code class="Dv">BUS_SPACE_MAP_PREFETCHABLE</code> or - <code class="Dv">BUS_SPACE_MAP_CACHEABLE</code> may be reordered or combined - for performance on devices that support it, such as write-combining (a.k.a. - ‘prefetchable’) graphics framebuffers or cacheable ROM images. - The - <a class="permalink" href="#bus_space_barrier"><code class="Fn">bus_space_barrier</code></a>() - function orders reads and writes in prefetchable or cacheable mappings - relative to other reads and writes in bus spaces. Barriers are needed - <a class="permalink" href="#only"><i class="Em" id="only">only</i></a> when - prefetchable or cacheable mappings are involved:</p> -<ul class="Bl-bullet"> - <li>Bus space reads and writes on non-prefetchable, non-cacheable mappings at - a single device are totally ordered with one another.</li> - <li>Ordering of memory operations on normal memory with bus space I/O for - triggering DMA or being notified of DMA completion requires - <a class="Xr">bus_dmamap_sync(9)</a>.</li> -</ul> -<p class="Pp">People trying to write portable drivers with the - <code class="Nm">bus_space</code> functions should try to make minimal - assumptions about what the system allows. In particular, they should expect - that the system requires bus space addresses being accessed to be naturally - aligned (i.e., base address of handle added to offset is a multiple of the - access size), and that the system does alignment checking on pointers (i.e., - pointer to objects being read and written must point to properly-aligned - data).</p> -<p class="Pp">The descriptions of the <code class="Nm">bus_space</code> - functions given below all assume that they are called with proper arguments. - If called with invalid arguments or arguments that are out of range (e.g., - trying to access data outside of the region mapped when a given handle was - created), undefined behaviour results. In that case, they may cause the - system to halt, either intentionally (via panic) or unintentionally (by - causing a fatal trap or by some other means) or may cause improper operation - which is not immediately fatal. Functions which return void or which return - data read from bus space (i.e., functions which don't obviously return an - error code) do not fail. They could only fail if given invalid arguments, - and in that case their behaviour is undefined. Functions which take a count - of bytes have undefined results if the specified <var class="Fa">count</var> - is zero.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="TYPES"><a class="permalink" href="#TYPES">TYPES</a></h1> -<p class="Pp">Several types are defined in - <code class="In"><<a class="In">machine/bus_defs.h</a>></code> to - facilitate use of the <code class="Nm">bus_space</code> functions by - drivers.</p> -<p class="Pp"></p> -<dl class="Bl-ohang Bl-compact"> - <dt><var class="Fa">bus_addr_t</var></dt> - <dd> - <p class="Pp">The <var class="Fa">bus_addr_t</var> type is used to describe - bus addresses. It must be an unsigned integral type capable of holding - the largest bus address usable by the architecture. This type is - primarily used when mapping and unmapping bus space.</p> - <p class="Pp"></p> - </dd> - <dt><var class="Fa">bus_size_t</var></dt> - <dd> - <p class="Pp">The <var class="Fa">bus_size_t</var> type is used to describe - sizes of ranges in bus space. It must be an unsigned integral type - capable of holding the size of the largest bus address range usable on - the architecture. This type is used by virtually all of the - <code class="Nm">bus_space</code> functions, describing sizes when - mapping regions and offsets into regions when performing space access - operations.</p> - <p class="Pp"></p> - </dd> - <dt><var class="Fa">bus_space_tag_t</var></dt> - <dd> - <p class="Pp">The <var class="Fa">bus_space_tag_t</var> type is used to - describe a particular bus space on a machine. Its contents are - machine-dependent and should be considered opaque by machine-independent - code. This type is used by all <code class="Nm">bus_space</code> - functions to name the space on which they're operating.</p> - <p class="Pp"></p> - </dd> - <dt><var class="Fa">bus_space_handle_t</var></dt> - <dd> - <p class="Pp">The <var class="Fa">bus_space_handle_t</var> type is used to - describe a mapping of a range of bus space. Its contents are - machine-dependent and should be considered opaque by machine-independent - code. This type is used when performing bus space access operations.</p> - <p class="Pp"></p> - </dd> - <dt><var class="Fa">bus_space_reservation_t</var></dt> - <dd> - <p class="Pp" id="bus_space_reservation_init">The - <var class="Fa">bus_space_reservation_t</var> type is used to describe a - range of bus space. It logically consists of a - <var class="Fa">bus_addr_t</var>, the first address in the range, and a - <var class="Fa">bus_size_t</var>, the length in bytes of the range. - Machine-independent code creates and interrogates a - <var class="Fa">bus_space_reservation_t</var> using a constructor, - <a class="permalink" href="#bus_space_reservation_init"><code class="Fn">bus_space_reservation_init</code></a>(), - and accessor functions, - <a class="permalink" href="#bus_space_reservation_addr"><code class="Fn" id="bus_space_reservation_addr">bus_space_reservation_addr</code></a>() - and - <a class="permalink" href="#bus_space_reservation_size"><code class="Fn" id="bus_space_reservation_size">bus_space_reservation_size</code></a>().</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="COMPARING_BUS_SPACE_TAGS"><a class="permalink" href="#COMPARING_BUS_SPACE_TAGS">COMPARING - BUS SPACE TAGS</a></h1> -<p class="Pp">To check whether or not one <var class="Fa">bus_space_tag_t</var> - refers to the same space as another in machine-independent code, do not use - either <a class="Xr">memcmp(9)</a> or the C equals (==) operator. Use - <a class="permalink" href="#bus_space_is_equal"><code class="Fn" id="bus_space_is_equal">bus_space_is_equal</code></a>(), - instead.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="MAPPING_AND_UNMAPPING_BUS_SPACE"><a class="permalink" href="#MAPPING_AND_UNMAPPING_BUS_SPACE">MAPPING - AND UNMAPPING BUS SPACE</a></h1> -<p class="Pp">Bus space must be mapped before it can be used, and should be - unmapped when it is no longer needed. The - <code class="Fn">bus_space_map</code>(), - <code class="Fn">bus_space_reservation_map</code>(), - <code class="Fn">bus_space_reservation_unmap</code>(), and - <code class="Fn">bus_space_unmap</code>() functions provide these - capabilities.</p> -<p class="Pp" id="bus_space_subregion">Some drivers need to be able to pass a - subregion of already-mapped bus space to another driver or module within a - driver. The - <a class="permalink" href="#bus_space_subregion"><code class="Fn">bus_space_subregion</code></a>() - function allows such subregions to be created.</p> -<p class="Pp"></p> -<dl class="Bl-ohang Bl-compact"> - <dt id="bus_space_map"><a class="permalink" href="#bus_space_map"><code class="Fn">bus_space_map</code></a>(<var class="Fa">space</var>, - <var class="Fa">address</var>, <var class="Fa">size</var>, - <var class="Fa">flags</var>, <var class="Fa">handlep</var>)</dt> - <dd> - <p class="Pp" id="bus_space_map~2">The - <a class="permalink" href="#bus_space_map~2"><code class="Fn">bus_space_map</code></a>() - function exclusively reserves and maps the region of bus space named by - the <var class="Fa">space</var>, <var class="Fa">address</var>, and - <var class="Fa">size</var> arguments. If successful, it returns zero and - fills in the bus space handle pointed to by - <var class="Fa">handlep</var> with the handle that can be used to access - the mapped region. If unsuccessful, it will return non-zero and leave - the bus space handle pointed to by <var class="Fa">handlep</var> in an - undefined state.</p> - <p class="Pp">The <var class="Fa">flags</var> argument controls how the - space is to be mapped. Supported flags include:</p> - <div class="Bd-indent"> - <dl class="Bl-tag"> - <dt id="BUS_SPACE_MAP_CACHEABLE"><a class="permalink" href="#BUS_SPACE_MAP_CACHEABLE"><code class="Dv">BUS_SPACE_MAP_CACHEABLE</code></a></dt> - <dd>Try to map the space so that accesses can be cached by the system - cache. If this flag is not specified, the implementation should map - the space so that it will not be cached. This mapping method will only - be useful in very rare occasions. - <p class="Pp">This flag must have a value of 1 on all implementations - for backward compatibility.</p> - </dd> - <dt id="BUS_SPACE_MAP_PREFETCHABLE"><a class="permalink" href="#BUS_SPACE_MAP_PREFETCHABLE"><code class="Dv">BUS_SPACE_MAP_PREFETCHABLE</code></a></dt> - <dd>Try to map the space so that accesses can be prefetched by the system, - and writes can be buffered. This means, accesses should be side effect - free (idempotent). The - <a class="permalink" href="#bus_space_barrier~2"><code class="Fn" id="bus_space_barrier~2">bus_space_barrier</code></a>() - methods will flush the write buffer or force actual read accesses. If - this flag is not specified, the implementation should map the space so - that it will not be prefetched or delayed.</dd> - <dt id="BUS_SPACE_MAP_LINEAR"><a class="permalink" href="#BUS_SPACE_MAP_LINEAR"><code class="Dv">BUS_SPACE_MAP_LINEAR</code></a></dt> - <dd>Try to map the space so that its contents can be accessed linearly via - normal memory access methods (e.g., pointer dereferencing and - structure accesses). The <code class="Fn">bus_space_vaddr</code>() - method can be used to obtain the kernel virtual address of the mapped - range. This is useful when software wants to do direct access to a - memory device, e.g., a frame buffer. If this flag is specified and - linear mapping is not possible, the - <code class="Fn">bus_space_map</code>() call should fail. If this flag - is not specified, the system may map the space in whatever way is most - convenient. Use of this mapping method is not encouraged for normal - device access; where linear access is not essential, use of the - <a class="permalink" href="#bus_space_read/write"><code class="Fn" id="bus_space_read/write">bus_space_read/write</code></a>() - methods is strongly recommended.</dd> - </dl> - </div> - <p class="Pp">Not all combinations of flags make sense or are supported with - all spaces. For instance, - <code class="Dv">BUS_SPACE_MAP_CACHEABLE</code> may be meaningless when - used on many systems' I/O port spaces, and on some systems - <code class="Dv">BUS_SPACE_MAP_LINEAR</code> without - <code class="Dv">BUS_SPACE_MAP_PREFETCHABLE</code> may never work. When - the system hardware or firmware provides hints as to how spaces should - be mapped (e.g., the PCI memory mapping registers' - "prefetchable" bit), those hints should be followed for - maximum compatibility. On some systems, requesting a mapping that cannot - be satisfied (e.g., requesting a non-prefetchable mapping when the - system can only provide a prefetchable one) will cause the request to - fail.</p> - <p class="Pp">Some implementations may keep track of use of bus space for - some or all bus spaces and refuse to allow duplicate allocations. This - is encouraged for bus spaces which have no notion of slot-specific space - addressing, such as ISA and VME, and for spaces which coexist with those - spaces (e.g., EISA and PCI memory and I/O spaces co-existing with ISA - memory and I/O spaces).</p> - <p class="Pp">Mapped regions may contain areas for which there is no device - on the bus. If space in those areas is accessed, the results are - bus-dependent.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_reservation_map"><a class="permalink" href="#bus_space_reservation_map"><code class="Fn">bus_space_reservation_map</code></a>(<var class="Fa">space</var>, - <var class="Fa">bsr</var>, <var class="Fa">flags</var>, - <var class="Fa">handlep</var>)</dt> - <dd> - <p class="Pp" id="bus_space_reservation_map~2">The - <a class="permalink" href="#bus_space_reservation_map~2"><code class="Fn">bus_space_reservation_map</code></a>() - function is similar to <code class="Fn">bus_space_map</code>() but it - maps a region of bus space that was previously reserved by a call to - <code class="Fn">bus_space_reserve</code>() or - <code class="Fn">bus_space_reserve_subregion</code>(). The region is - given by the <var class="Fa">space</var> and <var class="Fa">bsr</var> - arguments. If successful, it returns zero and fills in the bus space - handle pointed to by <var class="Fa">handlep</var> with the handle that - can be used to access the mapped region. If unsuccessful, it will return - non-zero and leave the bus space handle pointed to by - <var class="Fa">handlep</var> in an undefined state.</p> - <p class="Pp" id="bus_space_reservation_map~3">A region mapped by - <a class="permalink" href="#bus_space_reservation_map~3"><code class="Fn">bus_space_reservation_map</code></a>() - may only be unmapped by a call to - <code class="Fn">bus_space_reservation_unmap</code>().</p> - <p class="Pp" id="bus_space_map~3">For more details, see the description of - <a class="permalink" href="#bus_space_map~3"><code class="Fn">bus_space_map</code></a>().</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_unmap"><a class="permalink" href="#bus_space_unmap"><code class="Fn">bus_space_unmap</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">size</var>)</dt> - <dd> - <p class="Pp" id="bus_space_unmap~2">The - <a class="permalink" href="#bus_space_unmap~2"><code class="Fn">bus_space_unmap</code></a>() - function unmaps and relinquishes a region of bus space reserved and - mapped with <code class="Fn">bus_space_map</code>(). When unmapping a - region, the <var class="Fa">size</var> specified should be the same as - the size given to <code class="Fn">bus_space_map</code>() when mapping - that region.</p> - <p class="Pp" id="bus_space_unmap~3">After - <a class="permalink" href="#bus_space_unmap~3"><code class="Fn">bus_space_unmap</code></a>() - is called on a handle, that handle is no longer valid. (If copies were - made of the handle they are no longer valid, either.)</p> - <p class="Pp" id="bus_space_unmap~4">This function will never fail. If it - would fail (e.g., because of an argument error), that indicates a - software bug which should cause a panic. In that case, - <a class="permalink" href="#bus_space_unmap~4"><code class="Fn">bus_space_unmap</code></a>() - will never return.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_reservation_unmap"><a class="permalink" href="#bus_space_reservation_unmap"><code class="Fn">bus_space_reservation_unmap</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">size</var>)</dt> - <dd> - <p class="Pp" id="bus_space_reservation_unmap~2">The - <a class="permalink" href="#bus_space_reservation_unmap~2"><code class="Fn">bus_space_reservation_unmap</code></a>() - function is similar to <code class="Fn">bus_space_unmap</code>() but it - should be called on handles mapped by - <code class="Fn">bus_space_reservation_map</code>() and only on such - handles. Unlike <code class="Fn">bus_space_unmap</code>(), - <code class="Fn">bus_space_reservation_unmap</code>() does not - relinquish exclusive use of the bus space named by - <var class="Fa">handle</var> and <var class="Fa">size</var>; that is the - job of <code class="Fn">bus_space_release</code>().</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_subregion~2"><a class="permalink" href="#bus_space_subregion~2"><code class="Fn">bus_space_subregion</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">size</var>, <var class="Fa">nhandlep</var>)</dt> - <dd> - <p class="Pp" id="bus_space_subregion~3">The - <a class="permalink" href="#bus_space_subregion~3"><code class="Fn">bus_space_subregion</code></a>() - function is a convenience function which makes a new handle to some - subregion of an already-mapped region of bus space. The subregion - described by the new handle starts at byte offset - <var class="Fa">offset</var> into the region described by - <var class="Fa">handle</var>, with the size given by - <var class="Fa">size</var>, and must be wholly contained within the - original region.</p> - <p class="Pp" id="bus_space_subregion~4">If successful, - <a class="permalink" href="#bus_space_subregion~4"><code class="Fn">bus_space_subregion</code></a>() - returns zero and fills in the bus space handle pointed to by - <var class="Fa">nhandlep</var>. If unsuccessful, it returns non-zero and - leaves the bus space handle pointed to by <var class="Fa">nhandlep</var> - in an undefined state. In either case, the handle described by - <var class="Fa">handle</var> remains valid and is unmodified.</p> - <p class="Pp" id="bus_space_subregion~5">When done with a handle created by - <a class="permalink" href="#bus_space_subregion~5"><code class="Fn">bus_space_subregion</code></a>(), - the handle should be thrown away. Under no circumstances should - <code class="Fn">bus_space_unmap</code>() be used on the handle. Doing - so may confuse any resource management being done on the space, and will - result in undefined behaviour. When - <code class="Fn">bus_space_unmap</code>() or - <code class="Fn">bus_space_free</code>() is called on a handle, all - subregions of that handle become invalid.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_vaddr"><a class="permalink" href="#bus_space_vaddr"><code class="Fn">bus_space_vaddr</code></a>(<var class="Fa">tag</var>, - <var class="Fa">handle</var>)</dt> - <dd> - <p class="Pp" id="bus_space_barrier~3">This method returns the kernel - virtual address of a mapped bus space if and only if it was mapped with - the <code class="Dv">BUS_SPACE_MAP_LINEAR</code> flag. The range can be - accessed by normal (volatile) pointer dereferences. If mapped with the - <code class="Dv">BUS_SPACE_MAP_PREFETCHABLE</code> flag, the - <a class="permalink" href="#bus_space_barrier~3"><code class="Fn">bus_space_barrier</code></a>() - method must be used to force a particular access order.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_mmap"><a class="permalink" href="#bus_space_mmap"><code class="Fn">bus_space_mmap</code></a>(<var class="Fa">tag</var>, - <var class="Fa">addr</var>, <var class="Fa">off</var>, - <var class="Fa">prot</var>, <var class="Fa">flags</var>)</dt> - <dd> - <p class="Pp" id="bus_space_mmap~2">This method is used to provide support - for memory mapping bus space into user applications. If an address space - is addressable via volatile pointer dereferences, - <a class="permalink" href="#bus_space_mmap~2"><code class="Fn">bus_space_mmap</code></a>() - will return the physical address (possibly encoded as a - machine-dependent cookie) of the bus space indicated by - <var class="Fa">addr</var> and <var class="Fa">off</var>. - <var class="Fa">addr</var> is the base address of the device or device - region, and <var class="Fa">off</var> is the offset into that region - that is being requested. If the request is made with - <code class="Dv">BUS_SPACE_MAP_LINEAR</code> as a flag, then a linear - region must be returned to the caller. If the region cannot be mapped - (either the address does not exist, or the constraints can not be met), - <code class="Fn">bus_space_mmap</code>() returns - <code class="Dv">-1</code> to indicate failure.</p> - <p class="Pp" id="bus_space_mmap~3">Note that it is not necessary that the - region being requested by a - <a class="permalink" href="#bus_space_mmap~3"><code class="Fn">bus_space_mmap</code></a>() - call be mapped into a <var class="Fa">bus_space_handle_t</var>.</p> - <p class="Pp" id="bus_space_mmap~4"><a class="permalink" href="#bus_space_mmap~4"><code class="Fn">bus_space_mmap</code></a>() - is called once per <code class="Dv">PAGE_SIZE</code> page in the range. - The <var class="Fa">prot</var> argument indicates the memory protection - requested by the user application for the range.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_handle_is_equal"><a class="permalink" href="#bus_space_handle_is_equal"><code class="Fn">bus_space_handle_is_equal</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle1</var>, <var class="Fa">handle2</var>)</dt> - <dd>Use <code class="Fn">bus_space_handle_is_equal</code>() to check whether - or not <var class="Fa">handle1</var> and <var class="Fa">handle2</var> - refer to regions starting at the same address in the bus space - <var class="Fa">space</var>.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="ALLOCATING_AND_FREEING_BUS_SPACE"><a class="permalink" href="#ALLOCATING_AND_FREEING_BUS_SPACE">ALLOCATING - AND FREEING BUS SPACE</a></h1> -<p class="Pp">Some devices require or allow bus space to be allocated by the - operating system for device use. When the devices no longer need the space, - the operating system should free it for use by other devices. The - <code class="Fn">bus_space_alloc</code>(), - <code class="Fn">bus_space_free</code>(), - <code class="Fn">bus_space_reserve</code>(), - <code class="Fn">bus_space_reserve_subregion</code>(), and - <code class="Fn">bus_space_release</code>() functions provide these - capabilities. The functions <code class="Fn">bus_space_reserve</code>(), - <code class="Fn">bus_space_reserve_subregion</code>(), and - <code class="Fn">bus_space_release</code>() are not yet available on all - architectures.</p> -<p class="Pp"></p> -<dl class="Bl-ohang Bl-compact"> - <dt id="bus_space_alloc"><a class="permalink" href="#bus_space_alloc"><code class="Fn">bus_space_alloc</code></a>(<var class="Fa">space</var>, - <var class="Fa">reg_start</var>, <var class="Fa">reg_end</var>, - <var class="Fa">size</var>, <var class="Fa">alignment</var>, - <var class="Fa">boundary</var>, <var class="Fa">flags</var>, - <var class="Fa">addrp</var>, <var class="Fa">handlep</var>)</dt> - <dd> - <p class="Pp" id="bus_space_alloc~2">The - <a class="permalink" href="#bus_space_alloc~2"><code class="Fn">bus_space_alloc</code></a>() - function allocates and maps a region of bus space with the size given by - <var class="Fa">size</var>, corresponding to the given constraints. If - successful, it returns zero, fills in the bus address pointed to by - <var class="Fa">addrp</var> with the bus space address of the allocated - region, and fills in the bus space handle pointed to by - <var class="Fa">handlep</var> with the handle that can be used to access - that region. If unsuccessful, it returns non-zero and leaves the bus - address pointed to by <var class="Fa">addrp</var> and the bus space - handle pointed to by <var class="Fa">handlep</var> in an undefined - state.</p> - <p class="Pp" id="bus_space_alloc~3">Constraints on the allocation are given - by the <var class="Fa">reg_start</var>, <var class="Fa">reg_end</var>, - <var class="Fa">alignment</var>, and <var class="Fa">boundary</var> - parameters. The allocated region will start at or after - <var class="Fa">reg_start</var> and end before or at - <var class="Fa">reg_end</var>. The <var class="Fa">alignment</var> - constraint must be a power of two, and the allocated region will start - at an address that is an even multiple of that power of two. The - <var class="Fa">boundary</var> constraint, if non-zero, ensures that the - region is allocated so that <var class="Fa">first address in - region</var> / <var class="Fa">boundary</var> has the same value as - <var class="Fa">last address in region</var> / - <var class="Fa">boundary</var>. If the constraints cannot be met, - <a class="permalink" href="#bus_space_alloc~3"><code class="Fn">bus_space_alloc</code></a>() - will fail. It is an error to specify a set of constraints that can never - be met (for example, <var class="Fa">size</var> greater than - <var class="Fa">boundary</var>).</p> - <p class="Pp">The <var class="Fa">flags</var> parameter is the same as the - like-named parameter to <var class="Fa">bus_space_map</var>, the same - flag values should be used, and they have the same meanings.</p> - <p class="Pp" id="bus_space_alloc~4">Handles created by - <a class="permalink" href="#bus_space_alloc~4"><code class="Fn">bus_space_alloc</code></a>() - should only be freed with <code class="Fn">bus_space_free</code>(). - Trying to use <code class="Fn">bus_space_unmap</code>() on them causes - undefined behaviour. The <code class="Fn">bus_space_subregion</code>() - function can be used on handles created by - <code class="Fn">bus_space_alloc</code>().</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_reserve"><a class="permalink" href="#bus_space_reserve"><code class="Fn">bus_space_reserve</code></a>(<var class="Fa">t</var>, - <var class="Fa">bpa</var>, <var class="Fa">size</var>, - <var class="Fa">flags</var>, <var class="Fa">bsrp</var>)</dt> - <dd> - <p class="Pp" id="bus_space_reserve~2">The - <a class="permalink" href="#bus_space_reserve~2"><code class="Fn">bus_space_reserve</code></a>() - function reserves, for the caller's exclusive use, - <var class="Fa">size</var> bytes starting at the address - <var class="Fa">bpa</var> in the space referenced by - <var class="Fa">t</var>.</p> - <p class="Pp" id="bus_space_reserve~3"><a class="permalink" href="#bus_space_reserve~3"><code class="Fn">bus_space_reserve</code></a>() - does <a class="permalink" href="#not"><i class="Em" id="not">not</i></a> - map the space. The caller should use - <code class="Fn">bus_space_reservation_map</code>() to map the - reservation. <var class="Fa">flags</var> contains a hint how the caller - may map the reservation, later. Whenever possible, callers should pass - the same flags to <code class="Fn">bus_space_reserve</code>() as they - will pass to <code class="Fn">bus_space_reservation_map</code>() to map - the reservation.</p> - <p class="Pp" id="bus_space_reserve~4">On success, - <a class="permalink" href="#bus_space_reserve~4"><code class="Fn">bus_space_reserve</code></a>() - records the reservation at <var class="Fa">bsrp</var> and returns 0. On - failure, <var class="Fa">bsrp</var> is undefined, and - <code class="Fn">bus_space_reserve</code>() returns a non-zero error - code. Possible error codes include</p> - <div class="Bd-indent"> - <dl class="Bl-tag"> - <dt><code class="Er">ENOMEM</code></dt> - <dd>There was not sufficient bus space at <var class="Fa">bpa</var> to - satisfy the request.</dd> - <dt><code class="Er">EOPNOTSUPP</code></dt> - <dd><code class="Fn">bus_space_reserve</code>() is not supported on this - architecture, or <var class="Fa">flags</var> was incompatible with the - bus space represented by <var class="Fa">t</var>.</dd> - </dl> - </div> - <p class="Pp"></p> - </dd> - <dt id="bus_space_reserve_subregion"><a class="permalink" href="#bus_space_reserve_subregion"><code class="Fn">bus_space_reserve_subregion</code></a>(<var class="Fa">t</var>, - <var class="Fa">reg_start</var>, <var class="Fa">reg_end</var>, - <var class="Fa">size</var>, <var class="Fa">alignment</var>, - <var class="Fa">boundary</var>, <var class="Fa">flags</var>, - <var class="Fa">bsrp</var>)</dt> - <dd> - <p class="Pp" id="bus_space_reserve_subregion~2">The - <a class="permalink" href="#bus_space_reserve_subregion~2"><code class="Fn">bus_space_reserve_subregion</code></a>() - function reserves, for the caller's exclusive use, - <var class="Fa">size</var> bytes in the space referenced by - <var class="Fa">t</var>. The parameters <var class="Fa">reg_start</var>, - <var class="Fa">reg_end</var>, <var class="Fa">alignment</var>, - <var class="Fa">boundary</var>, and <var class="Fa">flags</var> each - work alike to the <code class="Fn">bus_space_alloc</code>() parameters - of the same names.</p> - <p class="Pp" id="bus_space_reserve_subregion~3">On success, - <a class="permalink" href="#bus_space_reserve_subregion~3"><code class="Fn">bus_space_reserve_subregion</code></a>() - records the reservation at <var class="Fa">bsrp</var> and returns 0. On - failure, <var class="Fa">bsrp</var> is undefined, and - <code class="Fn">bus_space_reserve_subregion</code>() returns a non-zero - error code. Possible error codes include</p> - <div class="Bd-indent"> - <dl class="Bl-tag"> - <dt><code class="Er">ENOMEM</code></dt> - <dd>There was not sufficient bus space at <var class="Fa">bpa</var> to - satisfy the request.</dd> - <dt><code class="Er">EOPNOTSUPP</code></dt> - <dd><code class="Fn">bus_space_reserve</code>() is not supported on this - architecture, or <var class="Fa">flags</var> was incompatible with the - bus space represented by <var class="Fa">t</var>.</dd> - </dl> - </div> - <p class="Pp"></p> - </dd> - <dt id="bus_space_release"><a class="permalink" href="#bus_space_release"><code class="Fn">bus_space_release</code></a>(<var class="Fa">t</var>, - <var class="Fa">bsr</var>)</dt> - <dd> - <p class="Pp" id="bus_space_release~2">The - <a class="permalink" href="#bus_space_release~2"><code class="Fn">bus_space_release</code></a>() - function releases the bus space <var class="Fa">bsr</var> in - <var class="Fa">t</var> that was previously reserved by - <code class="Fn">bus_space_reserve</code>() or - <code class="Fn">bus_space_reserve_subregion</code>().</p> - <p class="Pp" id="bus_space_release~3">If - <a class="permalink" href="#bus_space_release~3"><code class="Fn">bus_space_release</code></a>() - is called on a reservation that has been mapped by - <code class="Fn">bus_space_reservation_map</code>() without subsequently - being unmapped, the behavior of the system is undefined.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_free"><a class="permalink" href="#bus_space_free"><code class="Fn">bus_space_free</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">size</var>)</dt> - <dd> - <p class="Pp" id="bus_space_free~2">The - <a class="permalink" href="#bus_space_free~2"><code class="Fn">bus_space_free</code></a>() - function unmaps and frees a region of bus space mapped and allocated - with <code class="Fn">bus_space_alloc</code>(). When unmapping a region, - the <var class="Fa">size</var> specified should be the same as the size - given to <code class="Fn">bus_space_alloc</code>() when allocating the - region.</p> - <p class="Pp" id="bus_space_free~3">After - <a class="permalink" href="#bus_space_free~3"><code class="Fn">bus_space_free</code></a>() - is called on a handle, that handle is no longer valid. (If copies were - made of the handle, they are no longer valid, either.)</p> - <p class="Pp" id="bus_space_free~4">This function will never fail. If it - would fail (e.g., because of an argument error), that indicates a - software bug which should cause a panic. In that case, - <a class="permalink" href="#bus_space_free~4"><code class="Fn">bus_space_free</code></a>() - will never return.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="READING_AND_WRITING_SINGLE_DATA_ITEMS"><a class="permalink" href="#READING_AND_WRITING_SINGLE_DATA_ITEMS">READING - AND WRITING SINGLE DATA ITEMS</a></h1> -<p class="Pp">The simplest way to access bus space is to read or write a single - data item. The <code class="Fn">bus_space_read_N</code>() and - <code class="Fn">bus_space_write_N</code>() families of functions provide - the ability to read and write 1, 2, 4, and 8 byte data items on busses which - support those access sizes.</p> -<p class="Pp"></p> -<dl class="Bl-ohang Bl-compact"> - <dt id="bus_space_read_1"><a class="permalink" href="#bus_space_read_1"><code class="Fn">bus_space_read_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> - <dd></dd> - <dt id="bus_space_read_2"><a class="permalink" href="#bus_space_read_2"><code class="Fn">bus_space_read_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> - <dd></dd> - <dt id="bus_space_read_4"><a class="permalink" href="#bus_space_read_4"><code class="Fn">bus_space_read_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> - <dd></dd> - <dt id="bus_space_read_8"><a class="permalink" href="#bus_space_read_8"><code class="Fn">bus_space_read_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> - <dd> - <p class="Pp" id="bus_space_read_N">The - <a class="permalink" href="#bus_space_read_N"><code class="Fn">bus_space_read_N</code></a>() - family of functions reads a 1, 2, 4, or 8 byte data item from the offset - specified by <var class="Fa">offset</var> into the region specified by - <var class="Fa">handle</var> of the bus space specified by - <var class="Fa">space</var>. The location being read must lie within the - bus space region specified by <var class="Fa">handle</var>.</p> - <p class="Pp">For portability, the starting address of the region specified - by <var class="Fa">handle</var> plus the offset should be a multiple of - the size of data item being read. On some systems, not obeying this - requirement may cause incorrect data to be read, on others it may cause - a system crash.</p> - <p class="Pp" id="bus_space_read_N~2">Read operations done by the - <a class="permalink" href="#bus_space_read_N~2"><code class="Fn">bus_space_read_N</code></a>() - functions may be executed out of order with respect to other read and - write operations if either are on prefetchable or cacheable mappings - unless order is enforced by use of the - <code class="Fn">bus_space_barrier</code>() function.</p> - <p class="Pp">These functions will never fail. If they would fail (e.g., - because of an argument error), that indicates a software bug which - should cause a panic. In that case, they will never return.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_write_1"><a class="permalink" href="#bus_space_write_1"><code class="Fn">bus_space_write_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd></dd> - <dt id="bus_space_write_2"><a class="permalink" href="#bus_space_write_2"><code class="Fn">bus_space_write_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd></dd> - <dt id="bus_space_write_4"><a class="permalink" href="#bus_space_write_4"><code class="Fn">bus_space_write_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd></dd> - <dt id="bus_space_write_8"><a class="permalink" href="#bus_space_write_8"><code class="Fn">bus_space_write_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd> - <p class="Pp" id="bus_space_write_N">The - <a class="permalink" href="#bus_space_write_N"><code class="Fn">bus_space_write_N</code></a>() - family of functions writes a 1, 2, 4, or 8 byte data item to the offset - specified by <var class="Fa">offset</var> into the region specified by - <var class="Fa">handle</var> of the bus space specified by - <var class="Fa">space</var>. The location being written must lie within - the bus space region specified by <var class="Fa">handle</var>.</p> - <p class="Pp">For portability, the starting address of the region specified - by <var class="Fa">handle</var> plus the offset should be a multiple of - the size of data item being written. On some systems, not obeying this - requirement may cause incorrect data to be written, on others it may - cause a system crash.</p> - <p class="Pp" id="bus_space_write_N~2">Write operations done by the - <a class="permalink" href="#bus_space_write_N~2"><code class="Fn">bus_space_write_N</code></a>() - functions may be executed out of order with respect to other read and - write operations if either are on prefetchable or cacheable mappings - unless order is enforced by use of the - <code class="Fn">bus_space_barrier</code>() function.</p> - <p class="Pp">These functions will never fail. If they would fail (e.g., - because of an argument error), that indicates a software bug which - should cause a panic. In that case, they will never return.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="PROBING_BUS_SPACE_FOR_HARDWARE_WHICH_MAY_NOT_RESPOND"><a class="permalink" href="#PROBING_BUS_SPACE_FOR_HARDWARE_WHICH_MAY_NOT_RESPOND">PROBING - BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND</a></h1> -<p class="Pp">One problem with the - <a class="permalink" href="#bus_space_read_N~3"><code class="Fn" id="bus_space_read_N~3">bus_space_read_N</code></a>() - and <code class="Fn">bus_space_write_N</code>() family of functions is that - they provide no protection against exceptions which can occur when no - physical hardware or device responds to the read or write cycles. In such a - situation, the system typically would panic due to a kernel-mode bus error. - The <code class="Fn">bus_space_peek_N</code>() and - <code class="Fn">bus_space_poke_N</code>() family of functions provide a - mechanism to handle these exceptions gracefully without the risk of crashing - the system.</p> -<p class="Pp" id="bus_space_read_N~4">As with - <a class="permalink" href="#bus_space_read_N~4"><code class="Fn">bus_space_read_N</code></a>() - and <code class="Fn">bus_space_write_N</code>(), the peek and poke functions - provide the ability to read and write 1, 2, 4, and 8 byte data items on - busses which support those access sizes. All of the constraints specified in - the descriptions of the <code class="Fn">bus_space_read_N</code>() and - <code class="Fn">bus_space_write_N</code>() functions also apply to - <code class="Fn">bus_space_peek_N</code>() and - <code class="Fn">bus_space_poke_N</code>().</p> -<p class="Pp" id="bus_space_peek_N">The return value indicates the outcome of - the peek or poke operation. A return value of zero implies that a hardware - device is responding to the operation at the specified offset in the bus - space. A non-zero return value indicates that the kernel intercepted a - hardware exception (e.g., bus error) when the peek or poke operation was - attempted. Note that some busses are incapable of generating exceptions when - non-existent hardware is accessed. In such cases, these functions will - always return zero and the value of the data read by - <a class="permalink" href="#bus_space_peek_N"><code class="Fn">bus_space_peek_N</code></a>() - will be unspecified.</p> -<p class="Pp" id="bus_space_peek_N~2">Finally, it should be noted that at this - time the - <a class="permalink" href="#bus_space_peek_N~2"><code class="Fn">bus_space_peek_N</code></a>() - and <code class="Fn">bus_space_poke_N</code>() functions are not re-entrant - and should not, therefore, be used from within an interrupt service routine. - This constraint may be removed at some point in the future.</p> -<p class="Pp"></p> -<dl class="Bl-ohang Bl-compact"> - <dt id="bus_space_peek_1"><a class="permalink" href="#bus_space_peek_1"><code class="Fn">bus_space_peek_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>)</dt> - <dd></dd> - <dt id="bus_space_peek_2"><a class="permalink" href="#bus_space_peek_2"><code class="Fn">bus_space_peek_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>)</dt> - <dd></dd> - <dt id="bus_space_peek_4"><a class="permalink" href="#bus_space_peek_4"><code class="Fn">bus_space_peek_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>)</dt> - <dd></dd> - <dt id="bus_space_peek_8"><a class="permalink" href="#bus_space_peek_8"><code class="Fn">bus_space_peek_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>)</dt> - <dd> - <p class="Pp" id="bus_space_peek_N~3">The - <a class="permalink" href="#bus_space_peek_N~3"><code class="Fn">bus_space_peek_N</code></a>() - family of functions cautiously read a 1, 2, 4, or 8 byte data item from - the offset specified by <var class="Fa">offset</var> in the region - specified by <var class="Fa">handle</var> of the bus space specified by - <var class="Fa">space</var>. The data item read is stored in the - location pointed to by <var class="Fa">datap</var>. It is permissible - for <var class="Fa">datap</var> to be NULL, in which case the data item - will be discarded after being read.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_poke_1"><a class="permalink" href="#bus_space_poke_1"><code class="Fn">bus_space_poke_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd></dd> - <dt id="bus_space_poke_2"><a class="permalink" href="#bus_space_poke_2"><code class="Fn">bus_space_poke_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd></dd> - <dt id="bus_space_poke_4"><a class="permalink" href="#bus_space_poke_4"><code class="Fn">bus_space_poke_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd></dd> - <dt id="bus_space_poke_8"><a class="permalink" href="#bus_space_poke_8"><code class="Fn">bus_space_poke_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd> - <p class="Pp" id="bus_space_poke_N">The - <a class="permalink" href="#bus_space_poke_N"><code class="Fn">bus_space_poke_N</code></a>() - family of functions cautiously write a 1, 2, 4, or 8 byte data item - specified by <var class="Fa">value</var> to the offset specified by - <var class="Fa">offset</var> in the region specified by - <var class="Fa">handle</var> of the bus space specified by - <var class="Fa">space</var>.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="BARRIERS"><a class="permalink" href="#BARRIERS">BARRIERS</a></h1> -<p class="Pp">Devices that support prefetchable (also known as - ‘write-combining’) or cacheable I/O may be mapped with - <code class="Dv">BUS_SPACE_MAP_PREFETCHABLE</code> or - <code class="Dv">BUS_SPACE_MAP_CACHEABLE</code> for higher performance by - allowing bus space read and write operations to be reordered, fused, torn, - and/or cached by the system.</p> -<p class="Pp" id="bus_space_barrier~4">When a driver requires ordering, e.g. to - write to a command ring in bus space and then update the command ring - pointer, the - <a class="permalink" href="#bus_space_barrier~4"><code class="Fn">bus_space_barrier</code></a>() - function enforces it.</p> -<p class="Pp"></p> -<dl class="Bl-ohang Bl-compact"> - <dt id="bus_space_barrier~5"><a class="permalink" href="#bus_space_barrier~5"><code class="Fn">bus_space_barrier</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">length</var>, <var class="Fa">flags</var>)</dt> - <dd> - <p class="Pp" id="bus_space_barrier~6">The - <a class="permalink" href="#bus_space_barrier~6"><code class="Fn">bus_space_barrier</code></a>() - function enforces ordering of bus space read and write operations for - the specified subregion (described by the <var class="Fa">offset</var> - and <var class="Fa">length</var> parameters) of the region named by - <var class="Fa">handle</var> in the space named by - <var class="Fa">space</var>.</p> - <p class="Pp">The <var class="Fa">flags</var> argument controls what types - of operations are to be ordered. Supported flags are:</p> - <div class="Bd-indent"> - <dl class="Bl-tag"> - <dt id="BUS_SPACE_BARRIER_READ"><a class="permalink" href="#BUS_SPACE_BARRIER_READ"><code class="Dv">BUS_SPACE_BARRIER_READ</code></a></dt> - <dd>Guarantee that any program-prior bus space read on - <i class="Em">any</i> bus space has returned data from the device or - memory before any program-later bus space read, bus space write, or - memory access via - <a class="permalink" href="#bus_space_vaddr~2"><code class="Fn" id="bus_space_vaddr~2">bus_space_vaddr</code></a>(), - on the specified range in the given bus space. - <p class="Pp">This functions similarly to - <a class="Xr">membar_acquire(3)</a>, but additionally orders bus - space I/O which <a class="Xr">membar_ops(3)</a> may not.</p> - </dd> - <dt id="BUS_SPACE_BARRIER_WRITE"><a class="permalink" href="#BUS_SPACE_BARRIER_WRITE"><code class="Dv">BUS_SPACE_BARRIER_WRITE</code></a></dt> - <dd>Guarantee that any program-prior bus space read, bus space write, or - memory access via - <a class="permalink" href="#bus_space_vaddr~3"><code class="Fn" id="bus_space_vaddr~3">bus_space_vaddr</code></a>(), - on the specified range in the given bus space, has completed before - any program-later bus space write on <i class="Em">any</i> bus space. - <p class="Pp">This functions similarly to - <a class="Xr">membar_release(3)</a>, but additionally orders bus - space I/O which <a class="Xr">membar_ops(3)</a> may not.</p> - </dd> - <dt id="BUS_SPACE_BARRIER_READ~2"><a class="permalink" href="#BUS_SPACE_BARRIER_READ~2"><code class="Dv">BUS_SPACE_BARRIER_READ</code></a> - | - <a class="permalink" href="#BUS_SPACE_BARRIER_WRITE~2"><code class="Dv" id="BUS_SPACE_BARRIER_WRITE~2">BUS_SPACE_BARRIER_WRITE</code></a></dt> - <dd>Guarantee that any program-prior bus space read, bus space write, or - memory access via - <a class="permalink" href="#bus_space_vaddr~4"><code class="Fn" id="bus_space_vaddr~4">bus_space_vaddr</code></a>() - on <i class="Em">any</i> bus space has completed before any - program-later bus space read, bus space write, or memory access via - <code class="Fn">bus_space_vaddr</code>() on <i class="Em">any</i> bus - space. - <p class="Pp">Note that this is independent of the specified bus space - and range.</p> - <p class="Pp">This functions similarly to - <a class="Xr">membar_sync(3)</a>, but additionally orders bus space - I/O which <a class="Xr">membar_ops(3)</a> may not. This combination - is very unusual, and often much more expensive; most drivers do not - need it.</p> - </dd> - </dl> - </div> - <p class="Pp">Example: Consider a command ring in bus space with a command - ring pointer register, and a response ring in bus space with a response - ring pointer register.</p> - <div class="Bd Pp Li"> - <pre>error = bus_space_map(sc->sc_regt, ..., 0, &sc->sc_regh); -if (error) - ... -error = bus_space_map(sc->sc_memt, ..., BUS_SPACE_MAP_PREFETCHABLE, - &sc->sc_memh); -if (error) - ...</pre> - </div> - <p class="Pp">To submit a command (assuming there is space in the ring), - first write it out and then update the pointer:</p> - <div class="Bd Pp Li"> - <pre>i = sc->sc_nextcmdslot; -bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i), cmd); -bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 4, arg1); -bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 8, arg2); -... -bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 4*n, argn); -bus_space_barrier(sc->sc_memt, sc->sc_memh, CMDSLOT(i), 4*n, - BUS_SPACE_BARRIER_WRITE); -bus_space_write_4(sc->sc_regt, sc->sc_regh, CMDPTR, i); -sc->sc_nextcmdslot = (i + n + 1) % sc->sc_ncmdslots;</pre> - </div> - <p class="Pp">To obtain a response, read the pointer first and then the ring - data:</p> - <div class="Bd Pp Li"> - <pre>ptr = bus_space_read_4(sc->sc_regt, sc->sc_regh, RESPPTR); -while ((i = sc->sc_nextrespslot) != ptr) { - bus_space_barrier(sc->sc_memt, sc->sc_memh, RESPSLOT(i), 4, - BUS_SPACE_BARRIER_READ); - status = bus_space_read_4(sc->sc_memt, sc->sc_memh, RESPSLOT(i)); - handle_response(status); - sc->sc_nextrespslot = (i + 1) % sc->sc_nrespslots; -}</pre> - </div> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="REGION_OPERATIONS"><a class="permalink" href="#REGION_OPERATIONS">REGION - OPERATIONS</a></h1> -<p class="Pp">Some devices use buffers which are mapped as regions in bus space. - Often, drivers want to copy the contents of those buffers to or from memory, - e.g., into mbufs which can be passed to higher levels of the system or from - mbufs to be output to a network. In order to allow drivers to do this as - efficiently as possible, the - <a class="permalink" href="#bus_space_read_region_N"><code class="Fn" id="bus_space_read_region_N">bus_space_read_region_N</code></a>() - and <code class="Fn">bus_space_write_region_N</code>() families of functions - are provided.</p> -<p class="Pp" id="bus_space_copy_region_N">Drivers occasionally need to copy one - region of a bus space to another, or to set all locations in a region of bus - space to contain a single value. The - <a class="permalink" href="#bus_space_copy_region_N"><code class="Fn">bus_space_copy_region_N</code></a>() - family of functions and the <code class="Fn">bus_space_set_region_N</code>() - family of functions allow drivers to perform these operations.</p> -<p class="Pp"></p> -<dl class="Bl-ohang Bl-compact"> - <dt id="bus_space_read_region_1"><a class="permalink" href="#bus_space_read_region_1"><code class="Fn">bus_space_read_region_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_region_2"><a class="permalink" href="#bus_space_read_region_2"><code class="Fn">bus_space_read_region_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_region_4"><a class="permalink" href="#bus_space_read_region_4"><code class="Fn">bus_space_read_region_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_region_8"><a class="permalink" href="#bus_space_read_region_8"><code class="Fn">bus_space_read_region_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd> - <p class="Pp" id="bus_space_read_region_N~2">The - <a class="permalink" href="#bus_space_read_region_N~2"><code class="Fn">bus_space_read_region_N</code></a>() - family of functions reads <var class="Fa">count</var> 1, 2, 4, or 8 byte - data items from bus space starting at byte offset - <var class="Fa">offset</var> in the region specified by - <var class="Fa">handle</var> of the bus space specified by - <var class="Fa">space</var> and writes them into the array specified by - <var class="Fa">datap</var>. Each successive data item is read from an - offset 1, 2, 4, or 8 bytes after the previous data item (depending on - which function is used). All locations being read must lie within the - bus space region specified by <var class="Fa">handle</var>.</p> - <p class="Pp">For portability, the starting address of the region specified - by <var class="Fa">handle</var> plus the offset should be a multiple of - the size of data items being read and the data array pointer should be - properly aligned. On some systems, not obeying these requirements may - cause incorrect data to be read, on others it may cause a system - crash.</p> - <p class="Pp" id="bus_space_read_region_N~3">Read operations done by the - <a class="permalink" href="#bus_space_read_region_N~3"><code class="Fn">bus_space_read_region_N</code></a>() - functions may be executed in any order. They may also be executed out of - order with respect to other read and write operations if either are on - prefetchable or cacheable mappings unless order is enforced by use of - the <code class="Fn">bus_space_barrier</code>() function. There is no - way to insert barriers between reads of individual bus space locations - executed by the <code class="Fn">bus_space_read_region_N</code>() - functions.</p> - <p class="Pp">These functions will never fail. If they would fail (e.g., - because of an argument error), that indicates a software bug which - should cause a panic. In that case, they will never return.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_write_region_1"><a class="permalink" href="#bus_space_write_region_1"><code class="Fn">bus_space_write_region_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_region_2"><a class="permalink" href="#bus_space_write_region_2"><code class="Fn">bus_space_write_region_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_region_4"><a class="permalink" href="#bus_space_write_region_4"><code class="Fn">bus_space_write_region_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_region_8"><a class="permalink" href="#bus_space_write_region_8"><code class="Fn">bus_space_write_region_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd> - <p class="Pp" id="bus_space_write_region_N">The - <a class="permalink" href="#bus_space_write_region_N"><code class="Fn">bus_space_write_region_N</code></a>() - family of functions reads <var class="Fa">count</var> 1, 2, 4, or 8 byte - data items from the array specified by <var class="Fa">datap</var> and - writes them to bus space starting at byte offset - <var class="Fa">offset</var> in the region specified by - <var class="Fa">handle</var> of the bus space specified by - <var class="Fa">space</var>. Each successive data item is written to an - offset 1, 2, 4, or 8 bytes after the previous data item (depending on - which function is used). All locations being written must lie within the - bus space region specified by <var class="Fa">handle</var>.</p> - <p class="Pp">For portability, the starting address of the region specified - by <var class="Fa">handle</var> plus the offset should be a multiple of - the size of data items being written and the data array pointer should - be properly aligned. On some systems, not obeying these requirements may - cause incorrect data to be written, on others it may cause a system - crash.</p> - <p class="Pp" id="bus_space_write_region_N~2">Write operations done by the - <a class="permalink" href="#bus_space_write_region_N~2"><code class="Fn">bus_space_write_region_N</code></a>() - functions may be executed in any order. They may also be executed out of - order with respect to other read and write operations if either are on - prefetchable or cacheable mappings unless order is enforced by use of - the <code class="Fn">bus_space_barrier</code>() function. There is no - way to insert barriers between writes of individual bus space locations - executed by the <code class="Fn">bus_space_write_region_N</code>() - functions.</p> - <p class="Pp">These functions will never fail. If they would fail (e.g., - because of an argument error), that indicates a software bug which - should cause a panic. In that case, they will never return.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_copy_region_1"><a class="permalink" href="#bus_space_copy_region_1"><code class="Fn">bus_space_copy_region_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">srchandle</var>, <var class="Fa">srcoffset</var>, - <var class="Fa">dsthandle</var>, <var class="Fa">dstoffset</var>, - <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_copy_region_2"><a class="permalink" href="#bus_space_copy_region_2"><code class="Fn">bus_space_copy_region_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">srchandle</var>, <var class="Fa">srcoffset</var>, - <var class="Fa">dsthandle</var>, <var class="Fa">dstoffset</var>, - <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_copy_region_4"><a class="permalink" href="#bus_space_copy_region_4"><code class="Fn">bus_space_copy_region_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">srchandle</var>, <var class="Fa">srcoffset</var>, - <var class="Fa">dsthandle</var>, <var class="Fa">dstoffset</var>, - <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_copy_region_8"><a class="permalink" href="#bus_space_copy_region_8"><code class="Fn">bus_space_copy_region_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">srchandle</var>, <var class="Fa">srcoffset</var>, - <var class="Fa">dsthandle</var>, <var class="Fa">dstoffset</var>, - <var class="Fa">count</var>)</dt> - <dd> - <p class="Pp" id="bus_space_copy_region_N~2">The - <a class="permalink" href="#bus_space_copy_region_N~2"><code class="Fn">bus_space_copy_region_N</code></a>() - family of functions copies <var class="Fa">count</var> 1, 2, 4, or 8 - byte data items in bus space from the area starting at byte offset - <var class="Fa">srcoffset</var> in the region specified by - <var class="Fa">srchandle</var> of the bus space specified by - <var class="Fa">space</var> to the area starting at byte offset - <var class="Fa">dstoffset</var> in the region specified by - <var class="Fa">dsthandle</var> in the same bus space. Each successive - data item read or written has an offset 1, 2, 4, or 8 bytes after the - previous data item (depending on which function is used). All locations - being read and written must lie within the bus space region specified by - their respective handles.</p> - <p class="Pp">For portability, the starting addresses of the regions - specified by each handle plus its respective offset should be a multiple - of the size of data items being copied. On some systems, not obeying - this requirement may cause incorrect data to be copied, on others it may - cause a system crash.</p> - <p class="Pp" id="bus_space_copy_region_N~3">Read and write operations done - by the - <a class="permalink" href="#bus_space_copy_region_N~3"><code class="Fn">bus_space_copy_region_N</code></a>() - functions may be executed in any order. They may also be executed out of - order with respect to other read and write operations if either are on - prefetchable or cacheable mappings unless order is enforced by use of - the <code class="Fn">bus_space_barrier</code>() function. There is no - way to insert barriers between reads or writes of individual bus space - locations executed by the - <code class="Fn">bus_space_copy_region_N</code>() functions.</p> - <p class="Pp" id="bus_space_copy_region_N~4">Overlapping copies between - different subregions of a single region of bus space are handled - correctly by the - <a class="permalink" href="#bus_space_copy_region_N~4"><code class="Fn">bus_space_copy_region_N</code></a>() - functions.</p> - <p class="Pp">These functions will never fail. If they would fail (e.g., - because of an argument error), that indicates a software bug which - should cause a panic. In that case, they will never return.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_set_region_1"><a class="permalink" href="#bus_space_set_region_1"><code class="Fn">bus_space_set_region_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_set_region_2"><a class="permalink" href="#bus_space_set_region_2"><code class="Fn">bus_space_set_region_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_set_region_4"><a class="permalink" href="#bus_space_set_region_4"><code class="Fn">bus_space_set_region_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_set_region_8"><a class="permalink" href="#bus_space_set_region_8"><code class="Fn">bus_space_set_region_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>, <var class="Fa">count</var>)</dt> - <dd> - <p class="Pp" id="bus_space_set_region_N">The - <a class="permalink" href="#bus_space_set_region_N"><code class="Fn">bus_space_set_region_N</code></a>() - family of functions writes the given <var class="Fa">value</var> to - <var class="Fa">count</var> 1, 2, 4, or 8 byte data items in bus space - starting at byte offset <var class="Fa">offset</var> in the region - specified by <var class="Fa">handle</var> of the bus space specified by - <var class="Fa">space</var>. Each successive data item has an offset 1, - 2, 4, or 8 bytes after the previous data item (depending on which - function is used). All locations being written must lie within the bus - space region specified by <var class="Fa">handle</var>.</p> - <p class="Pp">For portability, the starting address of the region specified - by <var class="Fa">handle</var> plus the offset should be a multiple of - the size of data items being written. On some systems, not obeying this - requirement may cause incorrect data to be written, on others it may - cause a system crash.</p> - <p class="Pp" id="bus_space_set_region_N~2">Write operations done by the - <a class="permalink" href="#bus_space_set_region_N~2"><code class="Fn">bus_space_set_region_N</code></a>() - functions may be executed in any order. They may also be executed out of - order with respect to other read and write operations if either are on - prefetchable or cacheable mappings unless order is enforced by use of - the <code class="Fn">bus_space_barrier</code>() function. There is no - way to insert barriers between writes of individual bus space locations - executed by the <code class="Fn">bus_space_set_region_N</code>() - functions.</p> - <p class="Pp">These functions will never fail. If they would fail (e.g., - because of an argument error), that indicates a software bug which - should cause a panic. In that case, they will never return.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="READING_AND_WRITING_A_SINGLE_LOCATION_MULTIPLE_TIMES"><a class="permalink" href="#READING_AND_WRITING_A_SINGLE_LOCATION_MULTIPLE_TIMES">READING - AND WRITING A SINGLE LOCATION MULTIPLE TIMES</a></h1> -<p class="Pp">Some devices implement single locations in bus space which are to - be read or written multiple times to communicate data, e.g., some ethernet - devices' packet buffer FIFOs. In order to allow drivers to manipulate these - types of devices as efficiently as possible, the - <a class="permalink" href="#bus_space_read_multi_N"><code class="Fn" id="bus_space_read_multi_N">bus_space_read_multi_N</code></a>() - and <code class="Fn">bus_space_write_multi_N</code>() families of functions - are provided.</p> -<p class="Pp"></p> -<dl class="Bl-ohang Bl-compact"> - <dt id="bus_space_read_multi_1"><a class="permalink" href="#bus_space_read_multi_1"><code class="Fn">bus_space_read_multi_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_multi_2"><a class="permalink" href="#bus_space_read_multi_2"><code class="Fn">bus_space_read_multi_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_multi_4"><a class="permalink" href="#bus_space_read_multi_4"><code class="Fn">bus_space_read_multi_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_multi_8"><a class="permalink" href="#bus_space_read_multi_8"><code class="Fn">bus_space_read_multi_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd> - <p class="Pp" id="bus_space_read_multi_N~2">The - <a class="permalink" href="#bus_space_read_multi_N~2"><code class="Fn">bus_space_read_multi_N</code></a>() - family of functions reads <var class="Fa">count</var> 1, 2, 4, or 8 byte - data items from bus space at byte offset <var class="Fa">offset</var> in - the region specified by <var class="Fa">handle</var> of the bus space - specified by <var class="Fa">space</var> and writes them into the array - specified by <var class="Fa">datap</var>. Each successive data item is - read from the same location in bus space. The location being read must - lie within the bus space region specified by - <var class="Fa">handle</var>.</p> - <p class="Pp">For portability, the starting address of the region specified - by <var class="Fa">handle</var> plus the offset should be a multiple of - the size of data items being read and the data array pointer should be - properly aligned. On some systems, not obeying these requirements may - cause incorrect data to be read, on others it may cause a system - crash.</p> - <p class="Pp" id="bus_space_read_multi_N~3">Read operations done by the - <a class="permalink" href="#bus_space_read_multi_N~3"><code class="Fn">bus_space_read_multi_N</code></a>() - functions may be executed out of order with respect to other read and - write operations if the latter are on prefetchable or cacheable mappings - unless order is enforced by use of the - <code class="Fn">bus_space_barrier</code>() function. - <code class="Fn">bus_space_read_multi_N</code>() makes no sense itself - on prefetchable or cacheable mappings.</p> - <p class="Pp">These functions will never fail. If they would fail (e.g., - because of an argument error), that indicates a software bug which - should cause a panic. In that case, they will never return.</p> - <p class="Pp"></p> - </dd> - <dt id="bus_space_write_multi_1"><a class="permalink" href="#bus_space_write_multi_1"><code class="Fn">bus_space_write_multi_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_multi_2"><a class="permalink" href="#bus_space_write_multi_2"><code class="Fn">bus_space_write_multi_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_multi_4"><a class="permalink" href="#bus_space_write_multi_4"><code class="Fn">bus_space_write_multi_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_multi_8"><a class="permalink" href="#bus_space_write_multi_8"><code class="Fn">bus_space_write_multi_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd> - <p class="Pp" id="bus_space_write_multi_N">The - <a class="permalink" href="#bus_space_write_multi_N"><code class="Fn">bus_space_write_multi_N</code></a>() - family of functions reads <var class="Fa">count</var> 1, 2, 4, or 8 byte - data items from the array specified by <var class="Fa">datap</var> and - writes them into bus space at byte offset <var class="Fa">offset</var> - in the region specified by <var class="Fa">handle</var> of the bus space - specified by <var class="Fa">space</var>. Each successive data item is - written to the same location in bus space. The location being written - must lie within the bus space region specified by - <var class="Fa">handle</var>.</p> - <p class="Pp">For portability, the starting address of the region specified - by <var class="Fa">handle</var> plus the offset should be a multiple of - the size of data items being written and the data array pointer should - be properly aligned. On some systems, not obeying these requirements may - cause incorrect data to be written, on others it may cause a system - crash.</p> - <p class="Pp" id="bus_space_write_multi_N~2">Write operations done by the - <a class="permalink" href="#bus_space_write_multi_N~2"><code class="Fn">bus_space_write_multi_N</code></a>() - functions may be executed out of order with respect to other read and - write operations if the latter are on prefetchable or cacheable mappings - unless order is enforced by use of the - <code class="Fn">bus_space_barrier</code>() function. - <code class="Fn">bus_space_write_multi_N</code>() makes no sense itself - on prefetchable or cacheable mappings.</p> - <p class="Pp">These functions will never fail. If they would fail (e.g., - because of an argument error), that indicates a software bug which - should cause a panic. In that case, they will never return.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="STREAM_FUNCTIONS"><a class="permalink" href="#STREAM_FUNCTIONS">STREAM - FUNCTIONS</a></h1> -<p class="Pp">Most of the <code class="Nm">bus_space</code> functions imply a - host byte-order and a bus byte-order and take care of any translation for - the caller. In some cases, however, hardware may map a FIFO or some other - memory region for which the caller may want to use multi-word, yet - untranslated access. Access to these types of memory regions should be with - the - <a class="permalink" href="#bus_space_*_stream_N"><code class="Fn" id="bus_space_*_stream_N">bus_space_*_stream_N</code></a>() - functions.</p> -<p class="Pp"></p> -<dl class="Bl-ohang Bl-compact"> - <dt id="bus_space_read_stream_1"><a class="permalink" href="#bus_space_read_stream_1"><code class="Fn">bus_space_read_stream_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> - <dd></dd> - <dt id="bus_space_read_stream_2"><a class="permalink" href="#bus_space_read_stream_2"><code class="Fn">bus_space_read_stream_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> - <dd></dd> - <dt id="bus_space_read_stream_4"><a class="permalink" href="#bus_space_read_stream_4"><code class="Fn">bus_space_read_stream_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> - <dd></dd> - <dt id="bus_space_read_stream_8"><a class="permalink" href="#bus_space_read_stream_8"><code class="Fn">bus_space_read_stream_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> - <dd></dd> - <dt id="bus_space_read_multi_stream_1"><a class="permalink" href="#bus_space_read_multi_stream_1"><code class="Fn">bus_space_read_multi_stream_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_multi_stream_2"><a class="permalink" href="#bus_space_read_multi_stream_2"><code class="Fn">bus_space_read_multi_stream_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_multi_stream_4"><a class="permalink" href="#bus_space_read_multi_stream_4"><code class="Fn">bus_space_read_multi_stream_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_multi_stream_8"><a class="permalink" href="#bus_space_read_multi_stream_8"><code class="Fn">bus_space_read_multi_stream_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_region_stream_1"><a class="permalink" href="#bus_space_read_region_stream_1"><code class="Fn">bus_space_read_region_stream_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_region_stream_2"><a class="permalink" href="#bus_space_read_region_stream_2"><code class="Fn">bus_space_read_region_stream_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_region_stream_4"><a class="permalink" href="#bus_space_read_region_stream_4"><code class="Fn">bus_space_read_region_stream_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_read_region_stream_8"><a class="permalink" href="#bus_space_read_region_stream_8"><code class="Fn">bus_space_read_region_stream_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_stream_1"><a class="permalink" href="#bus_space_write_stream_1"><code class="Fn">bus_space_write_stream_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd></dd> - <dt id="bus_space_write_stream_2"><a class="permalink" href="#bus_space_write_stream_2"><code class="Fn">bus_space_write_stream_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd></dd> - <dt id="bus_space_write_stream_4"><a class="permalink" href="#bus_space_write_stream_4"><code class="Fn">bus_space_write_stream_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd></dd> - <dt id="bus_space_write_stream_8"><a class="permalink" href="#bus_space_write_stream_8"><code class="Fn">bus_space_write_stream_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">value</var>)</dt> - <dd></dd> - <dt id="bus_space_write_multi_stream_1"><a class="permalink" href="#bus_space_write_multi_stream_1"><code class="Fn">bus_space_write_multi_stream_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_multi_stream_2"><a class="permalink" href="#bus_space_write_multi_stream_2"><code class="Fn">bus_space_write_multi_stream_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_multi_stream_4"><a class="permalink" href="#bus_space_write_multi_stream_4"><code class="Fn">bus_space_write_multi_stream_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_multi_stream_8"><a class="permalink" href="#bus_space_write_multi_stream_8"><code class="Fn">bus_space_write_multi_stream_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_region_stream_1"><a class="permalink" href="#bus_space_write_region_stream_1"><code class="Fn">bus_space_write_region_stream_1</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_region_stream_2"><a class="permalink" href="#bus_space_write_region_stream_2"><code class="Fn">bus_space_write_region_stream_2</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_region_stream_4"><a class="permalink" href="#bus_space_write_region_stream_4"><code class="Fn">bus_space_write_region_stream_4</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> - <dt id="bus_space_write_region_stream_8"><a class="permalink" href="#bus_space_write_region_stream_8"><code class="Fn">bus_space_write_region_stream_8</code></a>(<var class="Fa">space</var>, - <var class="Fa">handle</var>, <var class="Fa">offset</var>, - <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> - <dd></dd> -</dl> -<p class="Pp">These functions are defined just as their non-stream counterparts, - except that they provide no byte-order translation.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="IMPLEMENTING_BUS_SPACES_IN_MACHINE-INDEPENDENT_CODE"><a class="permalink" href="#IMPLEMENTING_BUS_SPACES_IN_MACHINE-INDEPENDENT_CODE">IMPLEMENTING - BUS SPACES IN MACHINE-INDEPENDENT CODE</a></h1> -<dl class="Bl-ohang Bl-compact"> - <dt id="bus_space_tag_create"><a class="permalink" href="#bus_space_tag_create"><code class="Fn">bus_space_tag_create</code></a>(<var class="Fa">obst</var>, - <var class="Fa">present</var>, <var class="Fa">extpresent</var>, - <var class="Fa">ov</var>, <var class="Fa">ctx</var>, - <var class="Fa">bstp</var>)</dt> - <dd>Create a copy of the tag <var class="Fa">obst</var> at - <var class="Fa">*bstp</var>. Except for the behavior overridden by - <var class="Fa">ov</var>, <var class="Fa">*bstp</var> inherits the - behavior of <var class="Fa">obst</var> under - <code class="Nm">bus_space</code> calls. - <p class="Pp"><var class="Fa">ov</var> contains function pointers - corresponding to <code class="Nm">bus_space</code> routines. Each - function pointer has a corresponding bit in - <var class="Fa">present</var> or <var class="Fa">extpresent</var>, and - if that bit is 1, the function pointer overrides the corresponding - <code class="Nm">bus_space</code> call for the new tag. Any combination - of these bits may be set in <var class="Fa">present</var>:</p> - <p class="Pp"></p> - <dl class="Bl-tag Bl-compact"> - <dt id="BUS_SPACE_OVERRIDE_MAP"><a class="permalink" href="#BUS_SPACE_OVERRIDE_MAP"><code class="Dv">BUS_SPACE_OVERRIDE_MAP</code></a></dt> - <dd style="width: auto;"> </dd> - <dt id="BUS_SPACE_OVERRIDE_UNMAP"><a class="permalink" href="#BUS_SPACE_OVERRIDE_UNMAP"><code class="Dv">BUS_SPACE_OVERRIDE_UNMAP</code></a></dt> - <dd style="width: auto;"> </dd> - <dt id="BUS_SPACE_OVERRIDE_ALLOC"><a class="permalink" href="#BUS_SPACE_OVERRIDE_ALLOC"><code class="Dv">BUS_SPACE_OVERRIDE_ALLOC</code></a></dt> - <dd style="width: auto;"> </dd> - <dt id="BUS_SPACE_OVERRIDE_FREE"><a class="permalink" href="#BUS_SPACE_OVERRIDE_FREE"><code class="Dv">BUS_SPACE_OVERRIDE_FREE</code></a></dt> - <dd style="width: auto;"> </dd> - <dt id="BUS_SPACE_OVERRIDE_RESERVE"><a class="permalink" href="#BUS_SPACE_OVERRIDE_RESERVE"><code class="Dv">BUS_SPACE_OVERRIDE_RESERVE</code></a></dt> - <dd style="width: auto;"> </dd> - <dt id="BUS_SPACE_OVERRIDE_RELEASE"><a class="permalink" href="#BUS_SPACE_OVERRIDE_RELEASE"><code class="Dv">BUS_SPACE_OVERRIDE_RELEASE</code></a></dt> - <dd style="width: auto;"> </dd> - <dt id="BUS_SPACE_OVERRIDE_RESERVATION_MAP"><a class="permalink" href="#BUS_SPACE_OVERRIDE_RESERVATION_MAP"><code class="Dv">BUS_SPACE_OVERRIDE_RESERVATION_MAP</code></a></dt> - <dd style="width: auto;"> </dd> - <dt id="BUS_SPACE_OVERRIDE_RESERVATION_UNMAP"><a class="permalink" href="#BUS_SPACE_OVERRIDE_RESERVATION_UNMAP"><code class="Dv">BUS_SPACE_OVERRIDE_RESERVATION_UNMAP</code></a></dt> - <dd style="width: auto;"> </dd> - <dt id="BUS_SPACE_OVERRIDE_RESERVE_SUBREGION"><a class="permalink" href="#BUS_SPACE_OVERRIDE_RESERVE_SUBREGION"><code class="Dv">BUS_SPACE_OVERRIDE_RESERVE_SUBREGION</code></a></dt> - <dd style="width: auto;"> </dd> - </dl> - <p class="Pp" id="bus_space_tag_create~2"><a class="permalink" href="#bus_space_tag_create~2"><code class="Fn">bus_space_tag_create</code></a>() - does not copy <var class="Fa">ov</var>. After a new tag is created by - <code class="Fn">bus_space_tag_create</code>(), <var class="Fa">ov</var> - must not be destroyed until after the tag is destroyed by - <code class="Fn">bus_space_tag_destroy</code>().</p> - <p class="Pp">The first argument of every override-function is a - <var class="Vt">void *</var>, and <var class="Fa">ctx</var> is passed in - that argument.</p> - <p class="Pp">Return 0 if the call succeeds. Return - <code class="Er">EOPNOTSUPP</code> if the architecture does not support - overrides. Return <code class="Er">EINVAL</code> if - <var class="Fa">present</var> is 0, if <var class="Fa">ov</var> is - <code class="Dv">NULL</code>, or if <var class="Fa">present</var> - indicates that an override is present, but the corresponding override in - <var class="Fa">ov</var> is <code class="Dv">NULL</code>.</p> - <p class="Pp">If the call does not succeed, <var class="Fa">*bstp</var> is - undefined.</p> - </dd> - <dt id="bus_space_tag_destroy"><a class="permalink" href="#bus_space_tag_destroy"><code class="Fn">bus_space_tag_destroy</code></a>(<var class="Fa">bst</var>)</dt> - <dd>Destroy a tag, <var class="Fa">bst</var>, created by a prior call to - <code class="Fn">bus_space_tag_create</code>(). If - <var class="Fa">bst</var> was not created by - <code class="Fn">bus_space_tag_create</code>(), results are undefined. If - <var class="Fa">bst</var> was already destroyed, results are - undefined.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXPECTED_CHANGES_TO_THE_BUS_SPACE_FUNCTIONS"><a class="permalink" href="#EXPECTED_CHANGES_TO_THE_BUS_SPACE_FUNCTIONS">EXPECTED - CHANGES TO THE BUS_SPACE FUNCTIONS</a></h1> -<p class="Pp">The definition of the <code class="Nm">bus_space</code> functions - should not yet be considered finalized. There are several changes and - improvements which should be explored, including:</p> -<ul class="Bl-bullet"> - <li>Exporting the <code class="Nm">bus_space</code> functions to userland so - that applications (such as X servers) have easier, more portable access to - device space.</li> - <li>Redefining bus space tags and handles so that machine-independent bus - interface drivers (for example PCI to VME bridges) could define and - implement bus spaces without requiring machine-dependent code. If this is - done, it should be done in such a way that machine-dependent optimizations - should remain possible.</li> - <li>Converting bus spaces (such as PCI configuration space) which currently - use space-specific access methods to use the - <code class="Nm">bus_space</code> functions where that is - appropriate.</li> - <li>Redefining the way bus space is mapped and allocated, so that mapping and - allocation are done with bus specific functions which return bus space - tags. This would allow further optimization than is currently possible, - and would also ease translation of the <code class="Nm">bus_space</code> - functions into user space (since mapping in user space would look like it - just used a different bus-specific mapping function).</li> -</ul> -</section> -<section class="Sh"> -<h1 class="Sh" id="COMPATIBILITY"><a class="permalink" href="#COMPATIBILITY">COMPATIBILITY</a></h1> -<p class="Pp">The current version of the <code class="Nm">bus_space</code> - interface specification differs slightly from the original specification - that came into wide use. A few of the function names and arguments have - changed for consistency and increased functionality. Drivers that were - written to the old, deprecated specification can be compiled by defining the - <code class="Dv">__BUS_SPACE_COMPAT_OLDDEFS</code> preprocessor symbol - before including - <code class="In"><<a class="In">sys/bus.h</a>></code>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">membar_ops(3)</a>, <a class="Xr">bus_dma(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">bus_space</code> functions were introduced in - a different form (memory and I/O spaces were accessed via different sets of - functions) in <span class="Ux">NetBSD 1.2</span>. The functions were merged - to work on generic “spaces” early in the - <span class="Ux">NetBSD 1.3</span> development cycle, and many drivers were - converted to use them. This document was written later during the - <span class="Ux">NetBSD 1.3</span> development cycle and the specification - was updated to fix some consistency problems and to add some missing - functionality.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The <code class="Nm">bus_space</code> interfaces were designed and - implemented by the <span class="Ux">NetBSD</span> developer community. - Primary contributors and implementors were <span class="An">Chris - Demetriou</span>, <span class="An">Jason Thorpe</span>, and - <span class="An">Charles Hannum</span>, but the rest of the - <span class="Ux">NetBSD</span> developers and the user community played a - significant role in development.</p> -<p class="Pp"><span class="An">Chris Demetriou</span> wrote this manual - page.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">August 12, 2022</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |