2 # Copyright (c) 2015-2016 Landon Fuller <landonf@FreeBSD.org>
3 # Copyright (c) 2017 The FreeBSD Foundation
6 # Portions of this software were developed by Landon Fuller
7 # under sponsorship from the FreeBSD Foundation.
9 # Redistribution and use in source and binary forms, with or without
10 # modification, are permitted provided that the following conditions
12 # 1. Redistributions of source code must retain the above copyright
13 # notice, this list of conditions and the following disclaimer.
14 # 2. Redistributions in binary form must reproduce the above copyright
15 # notice, this list of conditions and the following disclaimer in the
16 # documentation and/or other materials provided with the distribution.
18 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
19 # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20 # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21 # IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
22 # INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 # (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24 # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
25 # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
26 # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
27 # USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 #include <sys/types.h>
35 #include <dev/bhnd/bhnd_types.h>
36 #include <dev/bhnd/bhnd_erom_types.h>
41 # bhnd(4) bus interface
45 /* forward declarations */
46 struct bhnd_board_info;
47 struct bhnd_core_info;
49 struct bhnd_dma_translation;
55 #include <sys/systm.h>
57 #include <dev/bhnd/bhndvar.h>
59 static bhnd_erom_class_t *
60 bhnd_bus_null_get_erom_class(driver_t *driver)
65 static struct bhnd_chipid *
66 bhnd_bus_null_get_chipid(device_t dev, device_t child)
68 panic("bhnd_bus_get_chipid unimplemented");
72 bhnd_bus_null_read_ioctl(device_t dev, device_t child, uint16_t *ioctl)
74 panic("bhnd_bus_read_ioctl unimplemented");
79 bhnd_bus_null_write_ioctl(device_t dev, device_t child, uint16_t value,
82 panic("bhnd_bus_write_ioctl unimplemented");
87 bhnd_bus_null_read_iost(device_t dev, device_t child, uint16_t *iost)
89 panic("bhnd_bus_read_iost unimplemented");
93 bhnd_bus_null_is_hw_suspended(device_t dev, device_t child)
95 panic("bhnd_bus_is_hw_suspended unimplemented");
99 bhnd_bus_null_reset_hw(device_t dev, device_t child, uint16_t ioctl)
101 panic("bhnd_bus_reset_hw unimplemented");
106 bhnd_bus_null_suspend_hw(device_t dev, device_t child)
108 panic("bhnd_bus_suspend_hw unimplemented");
111 static bhnd_attach_type
112 bhnd_bus_null_get_attach_type(device_t dev, device_t child)
114 panic("bhnd_bus_get_attach_type unimplemented");
118 bhnd_bus_null_read_board_info(device_t dev, device_t child,
119 struct bhnd_board_info *info)
121 panic("bhnd_bus_read_boardinfo unimplemented");
125 bhnd_bus_null_child_added(device_t dev, device_t child)
130 bhnd_bus_null_alloc_pmu(device_t dev, device_t child)
132 panic("bhnd_bus_alloc_pmu unimplemented");
136 bhnd_bus_null_release_pmu(device_t dev, device_t child)
138 panic("bhnd_bus_release_pmu unimplemented");
142 bhnd_bus_null_get_clock_latency(device_t dev, device_t child,
143 bhnd_clock clock, u_int *latency)
145 panic("bhnd_pmu_get_clock_latency unimplemented");
149 bhnd_bus_null_get_clock_freq(device_t dev, device_t child,
150 bhnd_clock clock, u_int *freq)
152 panic("bhnd_pmu_get_clock_freq unimplemented");
156 bhnd_bus_null_request_clock(device_t dev, device_t child,
159 panic("bhnd_bus_request_clock unimplemented");
163 bhnd_bus_null_enable_clocks(device_t dev, device_t child,
166 panic("bhnd_bus_enable_clocks unimplemented");
170 bhnd_bus_null_request_ext_rsrc(device_t dev, device_t child,
173 panic("bhnd_bus_request_ext_rsrc unimplemented");
177 bhnd_bus_null_release_ext_rsrc(device_t dev, device_t child,
180 panic("bhnd_bus_release_ext_rsrc unimplemented");
184 bhnd_bus_null_read_config(device_t dev, device_t child,
185 bus_size_t offset, void *value, u_int width)
187 panic("bhnd_bus_null_read_config unimplemented");
191 bhnd_bus_null_write_config(device_t dev, device_t child,
192 bus_size_t offset, void *value, u_int width)
194 panic("bhnd_bus_null_write_config unimplemented");
198 bhnd_bus_null_find_hostb_device(device_t dev)
203 static struct bhnd_service_registry *
204 bhnd_bus_null_get_service_registry(device_t dev)
206 panic("bhnd_bus_get_service_registry unimplemented");
210 bhnd_bus_null_is_hw_disabled(device_t dev, device_t child)
212 panic("bhnd_bus_is_hw_disabled unimplemented");
216 bhnd_bus_null_get_probe_order(device_t dev, device_t child)
218 panic("bhnd_bus_get_probe_order unimplemented");
222 bhnd_bus_null_get_intr_domain(device_t dev, device_t child, bool self)
229 bhnd_bus_null_get_intr_count(device_t dev, device_t child)
235 bhnd_bus_null_get_intr_ivec(device_t dev, device_t child, u_int intr,
238 panic("bhnd_bus_get_intr_ivec unimplemented");
242 bhnd_bus_null_map_intr(device_t dev, device_t child, u_int intr,
245 panic("bhnd_bus_map_intr unimplemented");
249 bhnd_bus_null_unmap_intr(device_t dev, device_t child, rman_res_t irq)
251 panic("bhnd_bus_unmap_intr unimplemented");
255 bhnd_bus_null_get_port_rid(device_t dev, device_t child,
256 bhnd_port_type port_type, u_int port, u_int region)
262 bhnd_bus_null_decode_port_rid(device_t dev, device_t child, int type,
263 int rid, bhnd_port_type *port_type, u_int *port, u_int *region)
269 bhnd_bus_null_get_region_addr(device_t dev, device_t child,
270 bhnd_port_type type, u_int port, u_int region, bhnd_addr_t *addr,
277 bhnd_bus_null_get_nvram_var(device_t dev, device_t child,
278 const char *name, void *buf, size_t *size, bhnd_nvram_type type)
286 * Return the bhnd(4) bus driver's device enumeration parser class.
288 * @param driver The bhnd bus driver instance.
290 STATICMETHOD bhnd_erom_class_t * get_erom_class {
292 } DEFAULT bhnd_bus_null_get_erom_class;
295 * Register a shared bus @p provider for a given @p service.
297 * @param dev The parent of @p child.
298 * @param child The requesting child device.
299 * @param provider The service provider to register.
300 * @param service The service for which @p provider will be registered.
303 * @retval EEXIST if an entry for @p service already exists.
304 * @retval non-zero if registering @p provider otherwise fails, a regular
305 * unix error code will be returned.
307 METHOD int register_provider {
311 bhnd_service_t service;
312 } DEFAULT bhnd_bus_generic_register_provider;
315 * Attempt to remove the @p service provider registration for @p provider.
317 * @param dev The parent of @p child.
318 * @param child The requesting child device.
319 * @param provider The service provider to be deregistered.
320 * @param service The service for which @p provider will be deregistered,
321 * or BHND_SERVICE_INVALID to remove all service
322 * registrations for @p provider.
325 * @retval EBUSY if active references to @p provider exist; @see
326 * BHND_BUS_RETAIN_PROVIDER() and
327 * BHND_BUS_RELEASE_PROVIDER().
329 METHOD int deregister_provider {
333 bhnd_service_t service;
334 } DEFAULT bhnd_bus_generic_deregister_provider;
337 * Retain and return a reference to the registered @p service provider, if any.
339 * @param dev The parent of @p child.
340 * @param child The requesting child device.
341 * @param service The service for which a provider should be returned.
343 * On success, the caller assumes ownership the returned provider, and
344 * is responsible for releasing this reference via
345 * BHND_BUS_RELEASE_PROVIDER().
347 * @retval device_t success
348 * @retval NULL if no provider is registered for @p service.
350 METHOD device_t retain_provider {
353 bhnd_service_t service;
354 } DEFAULT bhnd_bus_generic_retain_provider;
357 * Release a reference to a service provider previously returned by
358 * BHND_BUS_RETAIN_PROVIDER().
360 * @param dev The parent of @p child.
361 * @param child The requesting child device.
362 * @param provider The provider to be released.
363 * @param service The service for which @p provider was previously
366 METHOD void release_provider {
370 bhnd_service_t service;
371 } DEFAULT bhnd_bus_generic_release_provider;
374 * Return a struct bhnd_service_registry.
376 * Used by drivers which use bhnd_bus_generic_sr_register_provider() etc.
377 * to implement service provider registration. It should return a service
378 * registry that may be used to resolve provider requests from @p child.
380 * @param dev The parent of @p child.
381 * @param child The requesting child device.
383 METHOD struct bhnd_service_registry * get_service_registry {
386 } DEFAULT bhnd_bus_null_get_service_registry;
389 * Return the active host bridge core for the bhnd bus, if any.
391 * @param dev The bhnd bus device.
393 * @retval device_t if a hostb device exists
394 * @retval NULL if no hostb device is found.
396 METHOD device_t find_hostb_device {
398 } DEFAULT bhnd_bus_null_find_hostb_device;
401 * Return true if the hardware components required by @p child are unpopulated
402 * or otherwise unusable.
404 * In some cases, enumerated devices may have pins that are left floating, or
405 * the hardware may otherwise be non-functional; this method allows a parent
406 * device to explicitly specify if a successfully enumerated @p child should
409 * @param dev The device whose child is being examined.
410 * @param child The child device.
412 METHOD bool is_hw_disabled {
415 } DEFAULT bhnd_bus_null_is_hw_disabled;
418 * Return the probe (and attach) order for @p child.
420 * All devices on the bhnd(4) bus will be probed, attached, or resumed in
421 * ascending order; they will be suspended, shutdown, and detached in
424 * The following device methods will be dispatched in ascending probe order
431 * The following device methods will be dispatched in descending probe order
434 * - DEVICE_SHUTDOWN()
438 * @param dev The device whose child is being examined.
439 * @param child The child device.
441 * Refer to BHND_PROBE_* and BHND_PROBE_ORDER_* for the standard set of
444 METHOD int get_probe_order {
447 } DEFAULT bhnd_bus_null_get_probe_order;
450 * Return the BHND chip identification for the parent bus.
452 * @param dev The device whose child is being examined.
453 * @param child The child device.
455 METHOD const struct bhnd_chipid * get_chipid {
458 } DEFAULT bhnd_bus_null_get_chipid;
461 * Return the BHND attachment type of the parent bus.
463 * @param dev The device whose child is being examined.
464 * @param child The child device.
466 * @retval BHND_ATTACH_ADAPTER if the bus is resident on a bridged adapter,
467 * such as a WiFi chipset.
468 * @retval BHND_ATTACH_NATIVE if the bus provides hardware services (clock,
469 * CPU, etc) to a directly attached native host.
471 METHOD bhnd_attach_type get_attach_type {
474 } DEFAULT bhnd_bus_null_get_attach_type;
478 * Find the best available DMA address translation capable of mapping a
479 * physical host address to a BHND DMA device address of @p width with
482 * @param dev The parent of @p child.
483 * @param child The bhnd device requesting the DMA address translation.
484 * @param width The address width within which the translation window must
485 * reside (see BHND_DMA_ADDR_*).
486 * @param flags Required translation flags (see BHND_DMA_TRANSLATION_*).
487 * @param[out] dmat On success, will be populated with a DMA tag specifying the
488 * @p translation DMA address restrictions. This argment may be NULL if the DMA
489 * tag is not desired.
490 * the set of valid host DMA addresses reachable via @p translation.
491 * @param[out] translation On success, will be populated with a DMA address
492 * translation descriptor for @p child. This argment may be NULL if the
493 * descriptor is not desired.
496 * @retval ENODEV If DMA is not supported.
497 * @retval ENOENT If no DMA translation matching @p width and @p flags is
499 * @retval non-zero If determining the DMA address translation for @p child
500 * otherwise fails, a regular unix error code will be returned.
502 METHOD int get_dma_translation {
508 struct bhnd_dma_translation *translation;
509 } DEFAULT bhnd_bus_generic_get_dma_translation;
512 * Attempt to read the BHND board identification from the parent bus.
514 * This relies on NVRAM access, and will fail if a valid NVRAM device cannot
515 * be found, or is not yet attached.
517 * @param dev The parent of @p child.
518 * @param child The bhnd device requesting board info.
519 * @param[out] info On success, will be populated with the bhnd(4) device's
523 * @retval ENODEV No valid NVRAM source could be found.
524 * @retval non-zero If reading @p name otherwise fails, a regular unix
525 * error code will be returned.
527 METHOD int read_board_info {
530 struct bhnd_board_info *info;
531 } DEFAULT bhnd_bus_null_read_board_info;
534 * Notify a bhnd bus that a child was added.
536 * This method must be called by concrete bhnd(4) driver impementations
537 * after @p child's bus state is fully initialized.
539 * @param dev The bhnd bus whose child is being added.
540 * @param child The child added to @p dev.
542 METHOD void child_added {
545 } DEFAULT bhnd_bus_null_child_added;
548 * Read the current value of @p child's I/O control register.
550 * @param dev The bhnd bus parent of @p child.
551 * @param child The bhnd device for which the I/O control register should be
553 * @param[out] ioctl On success, the I/O control register value.
556 * @retval EINVAL If @p child is not a direct child of @p dev.
557 * @retval ENODEV If agent/config space for @p child is unavailable.
558 * @retval non-zero If reading the IOCTL register otherwise fails, a regular
559 * unix error code will be returned.
561 METHOD int read_ioctl {
565 } DEFAULT bhnd_bus_null_read_ioctl;
568 * Write @p value with @p mask to @p child's I/O control register.
570 * @param dev The bhnd bus parent of @p child.
571 * @param child The bhnd device for which the I/O control register should
573 * @param value The value to be written (see also BHND_IOCTL_*).
574 * @param mask Only the bits defined by @p mask will be updated from @p value.
577 * @retval EINVAL If @p child is not a direct child of @p dev.
578 * @retval ENODEV If agent/config space for @p child is unavailable.
579 * @retval non-zero If writing the IOCTL register otherwise fails, a regular
580 * unix error code will be returned.
582 METHOD int write_ioctl {
587 } DEFAULT bhnd_bus_null_write_ioctl;
590 * Read the current value of @p child's I/O status register.
592 * @param dev The bhnd bus parent of @p child.
593 * @param child The bhnd device for which the I/O status register should be
595 * @param[out] iost On success, the I/O status register value.
598 * @retval EINVAL If @p child is not a direct child of @p dev.
599 * @retval ENODEV If agent/config space for @p child is unavailable.
600 * @retval non-zero If reading the IOST register otherwise fails, a regular
601 * unix error code will be returned.
603 METHOD int read_iost {
607 } DEFAULT bhnd_bus_null_read_iost;
611 * Return true if the given bhnd device's hardware is currently held
612 * in a RESET state or otherwise not clocked (BHND_IOCTL_CLK_EN).
614 * @param dev The bhnd bus parent of @p child.
615 * @param child The device to query.
617 * @retval true If @p child is held in RESET or not clocked (BHND_IOCTL_CLK_EN),
618 * or an error occured determining @p child's hardware state.
619 * @retval false If @p child is clocked and is not held in RESET.
621 METHOD bool is_hw_suspended {
624 } DEFAULT bhnd_bus_null_is_hw_suspended;
627 * Place the bhnd(4) device's hardware into a reset state, and then bring the
628 * hardware out of reset with BHND_IOCTL_CLK_EN and @p ioctl flags set.
630 * Any clock or resource PMU requests previously made by @p child will be
633 * @param dev The bhnd bus parent of @p child.
634 * @param child The device to be reset.
635 * @param ioctl Device-specific core ioctl flags to be supplied on reset
636 * (see BHND_IOCTL_*).
639 * @retval non-zero error
641 METHOD int reset_hw {
645 } DEFAULT bhnd_bus_null_reset_hw;
648 * Suspend @p child's hardware in a low-power reset state.
650 * Any clock or resource PMU requests previously made by @p dev will be
653 * The hardware may be brought out of reset via bhnd_reset_hw().
655 * @param dev The bhnd bus parent of @P child.
656 * @param dev The device to be suspended.
659 * @retval non-zero error
661 METHOD int suspend_hw {
664 } DEFAULT bhnd_bus_null_suspend_hw;
667 * Allocate per-core PMU resources and enable PMU request handling for @p child.
669 * The region containing the core's PMU register block (if any) must be
670 * allocated via bus_alloc_resource(9) (or bhnd_alloc_resource) before
671 * calling BHND_BUS_ALLOC_PMU(), and must not be released until after
672 * calling BHND_BUS_RELEASE_PMU().
674 * @param dev The parent of @p child.
675 * @param child The requesting bhnd device.
678 * @retval non-zero if enabling per-core PMU request handling fails, a
679 * regular unix error code will be returned.
681 METHOD int alloc_pmu {
684 } DEFAULT bhnd_bus_null_alloc_pmu;
687 * Release per-core PMU resources allocated for @p child. Any
688 * outstanding PMU requests are discarded.
690 * @param dev The parent of @p child.
691 * @param child The requesting bhnd device.
693 METHOD int release_pmu {
696 } DEFAULT bhnd_bus_null_release_pmu;
699 * Return the transition latency required for @p clock in microseconds, if
702 * The BHND_CLOCK_HT latency value is suitable for use as the D11 core's
703 * 'fastpwrup_dly' value.
705 * @note A driver must ask the bhnd bus to allocate PMU request state
706 * via BHND_BUS_ALLOC_PMU() before querying PMU clocks.
708 * @param dev The parent of @p child.
709 * @param child The requesting bhnd device.
710 * @param clock The clock to be queried for transition latency.
711 * @param[out] latency On success, the transition latency of @p clock in
715 * @retval ENODEV If the transition latency for @p clock is not available.
717 METHOD int get_clock_latency {
722 } DEFAULT bhnd_bus_null_get_clock_latency;
725 * Return the frequency for @p clock in Hz, if known.
727 * @param dev The parent of @p child.
728 * @param child The requesting bhnd device.
729 * @param clock The clock to be queried.
730 * @param[out] freq On success, the frequency of @p clock in Hz.
732 * @note A driver must ask the bhnd bus to allocate PMU request state
733 * via BHND_BUS_ALLOC_PMU() before querying PMU clocks.
736 * @retval ENODEV If the frequency for @p clock is not available.
738 METHOD int get_clock_freq {
743 } DEFAULT bhnd_bus_null_get_clock_freq;
746 * Request that @p clock (or faster) be routed to @p child.
748 * @note A driver must ask the bhnd bus to allocate PMU request state
749 * via BHND_BUS_ALLOC_PMU() before it can request clock resources.
751 * @note Any outstanding PMU clock requests will be discarded upon calling
752 * BHND_BUS_RESET_HW() or BHND_BUS_SUSPEND_HW().
754 * @param dev The parent of @p child.
755 * @param child The bhnd device requesting @p clock.
756 * @param clock The requested clock source.
759 * @retval ENODEV If an unsupported clock was requested.
760 * @retval ETIMEDOUT If the clock request succeeds, but the clock is not
761 * detected as ready within the PMU's maximum transition
762 * delay. This should not occur in normal operation.
764 METHOD int request_clock {
768 } DEFAULT bhnd_bus_null_request_clock;
771 * Request that @p clocks be powered on behalf of @p child.
773 * This will power on clock sources (e.g. XTAL, PLL, etc) required for
774 * @p clocks and wait until they are ready, discarding any previous
775 * requests by @p child.
777 * @note A driver must ask the bhnd bus to allocate PMU request state
778 * via BHND_BUS_ALLOC_PMU() before it can request clock resources.
780 * @note Any outstanding PMU clock requests will be discarded upon calling
781 * BHND_BUS_RESET_HW() or BHND_BUS_SUSPEND_HW().
783 * @param dev The parent of @p child.
784 * @param child The bhnd device requesting @p clock.
785 * @param clock The requested clock source.
788 * @retval ENODEV If an unsupported clock was requested.
789 * @retval ETIMEDOUT If the clock request succeeds, but the clock is not
790 * detected as ready within the PMU's maximum transition
791 * delay. This should not occur in normal operation.
793 METHOD int enable_clocks {
797 } DEFAULT bhnd_bus_null_enable_clocks;
800 * Power up an external PMU-managed resource assigned to @p child.
802 * @note A driver must ask the bhnd bus to allocate PMU request state
803 * via BHND_BUS_ALLOC_PMU() before it can request PMU resources.
805 * @note Any outstanding PMU resource requests will be released upon calling
806 * BHND_BUS_RESET_HW() or BHND_BUS_SUSPEND_HW().
808 * @param dev The parent of @p child.
809 * @param child The bhnd device requesting @p rsrc.
810 * @param rsrc The core-specific external resource identifier.
813 * @retval ENODEV If the PMU does not support @p rsrc.
814 * @retval ETIMEDOUT If the clock request succeeds, but the clock is not
815 * detected as ready within the PMU's maximum transition
816 * delay. This should not occur in normal operation.
818 METHOD int request_ext_rsrc {
822 } DEFAULT bhnd_bus_null_request_ext_rsrc;
825 * Power down an external PMU-managed resource assigned to @p child.
827 * @note A driver must ask the bhnd bus to allocate PMU request state
828 * via BHND_BUS_ALLOC_PMU() before it can request PMU resources.
830 * @param dev The parent of @p child.
831 * @param child The bhnd device requesting @p rsrc.
832 * @param rsrc The core-specific external resource number.
835 * @retval ENODEV If the PMU does not support @p rsrc.
836 * @retval ETIMEDOUT If the clock request succeeds, but the clock is not
837 * detected as ready within the PMU's maximum transition
838 * delay. This should not occur in normal operation.
840 METHOD int release_ext_rsrc {
844 } DEFAULT bhnd_bus_null_release_ext_rsrc;
847 * Read @p width bytes at @p offset from the bus-specific agent/config
850 * @param dev The parent of @p child.
851 * @param child The bhnd device for which @p offset should be read.
852 * @param offset The offset to be read.
853 * @param[out] value On success, the bytes read at @p offset.
854 * @param width The size of the access. Must be 1, 2 or 4 bytes.
856 * The exact behavior of this method is bus-specific. On a bcma(4) bus, this
857 * method provides access to the first agent port of @p child; on a siba(4) bus,
858 * this method provides access to the core's CFG0 register block.
860 * @note Device drivers should only use this API for functionality
861 * that is not available via another bhnd(4) function.
864 * @retval EINVAL If @p child is not a direct child of @p dev.
865 * @retval EINVAL If @p width is not one of 1, 2, or 4 bytes.
866 * @retval ENODEV If accessing agent/config space for @p child is unsupported.
867 * @retval EFAULT If reading @p width at @p offset exceeds the bounds of
868 * the mapped agent/config space for @p child.
870 METHOD int read_config {
876 } DEFAULT bhnd_bus_null_read_config;
879 * Read @p width bytes at @p offset from the bus-specific agent/config
882 * @param dev The parent of @p child.
883 * @param child The bhnd device for which @p offset should be read.
884 * @param offset The offset to be written.
885 * @param value A pointer to the value to be written.
886 * @param width The size of @p value. Must be 1, 2 or 4 bytes.
888 * The exact behavior of this method is bus-specific. In the case of
889 * bcma(4), this method provides access to the first agent port of @p child.
891 * @note Device drivers should only use this API for functionality
892 * that is not available via another bhnd(4) function.
895 * @retval EINVAL If @p child is not a direct child of @p dev.
896 * @retval EINVAL If @p width is not one of 1, 2, or 4 bytes.
897 * @retval ENODEV If accessing agent/config space for @p child is unsupported.
898 * @retval EFAULT If reading @p width at @p offset exceeds the bounds of
899 * the mapped agent/config space for @p child.
901 METHOD int write_config {
907 } DEFAULT bhnd_bus_null_write_config;
910 * Allocate a bhnd resource.
912 * This method's semantics are functionally identical to the bus API of the same
913 * name; refer to BUS_ALLOC_RESOURCE for complete documentation.
915 METHOD struct bhnd_resource * alloc_resource {
924 } DEFAULT bhnd_bus_generic_alloc_resource;
927 * Release a bhnd resource.
929 * This method's semantics are functionally identical to the bus API of the same
930 * name; refer to BUS_RELEASE_RESOURCE for complete documentation.
932 METHOD int release_resource {
937 struct bhnd_resource *res;
938 } DEFAULT bhnd_bus_generic_release_resource;
941 * Activate a bhnd resource.
943 * This method's semantics are functionally identical to the bus API of the same
944 * name; refer to BUS_ACTIVATE_RESOURCE for complete documentation.
946 METHOD int activate_resource {
951 struct bhnd_resource *r;
952 } DEFAULT bhnd_bus_generic_activate_resource;
955 * Deactivate a bhnd resource.
957 * This method's semantics are functionally identical to the bus API of the same
958 * name; refer to BUS_DEACTIVATE_RESOURCE for complete documentation.
960 METHOD int deactivate_resource {
965 struct bhnd_resource *r;
966 } DEFAULT bhnd_bus_generic_deactivate_resource;
969 * Return the interrupt domain.
971 * This globally unique value may be used as the interrupt controller 'xref'
972 * on targets that support INTRNG.
974 * @param dev The device whose child is being examined.
975 * @param child The child device.
976 * @parem self If true, return @p child's interrupt domain, rather than the
977 * domain in which @p child resides.
979 * On Non-OFW targets, this should either return:
980 * - The pointer address of a device that can uniquely identify @p child's
981 * interrupt domain (e.g., the bhnd bus' device_t address), or
982 * - 0 if unsupported by the bus.
984 * On OFW (including FDT) targets, this should return the @p child's iparent
985 * property's xref if @p self is false, the child's own node xref value if
986 * @p self is true, or 0 if no interrupt parent is found.
988 METHOD uintptr_t get_intr_domain {
992 } DEFAULT bhnd_bus_null_get_intr_domain;
995 * Return the number of interrupt lines assigned to @p child.
997 * @param dev The bhnd device whose child is being examined.
998 * @param child The child device.
1000 METHOD u_int get_intr_count {
1003 } DEFAULT bhnd_bus_null_get_intr_count;
1006 * Get the backplane interrupt vector of the @p intr line attached to @p child.
1008 * @param dev The device whose child is being examined.
1009 * @param child The child device.
1010 * @param intr The index of the interrupt line being queried.
1011 * @param[out] ivec On success, the assigned hardware interrupt vector will be
1012 * written to this pointer.
1014 * On bcma(4) devices, this returns the OOB bus line assigned to the
1017 * On siba(4) devices, this returns the target OCP slave flag number assigned
1021 * @retval ENXIO If @p intr exceeds the number of interrupt lines
1022 * assigned to @p child.
1024 METHOD int get_intr_ivec {
1029 } DEFAULT bhnd_bus_null_get_intr_ivec;
1032 * Map the given @p intr to an IRQ number; until unmapped, this IRQ may be used
1033 * to allocate a resource of type SYS_RES_IRQ.
1035 * On success, the caller assumes ownership of the interrupt mapping, and
1036 * is responsible for releasing the mapping via BHND_BUS_UNMAP_INTR().
1038 * @param dev The bhnd bus device.
1039 * @param child The requesting child device.
1040 * @param intr The interrupt being mapped.
1041 * @param[out] irq On success, the bus interrupt value mapped for @p intr.
1043 * @retval 0 If an interrupt was assigned.
1044 * @retval non-zero If mapping an interrupt otherwise fails, a regular
1045 * unix error code will be returned.
1047 METHOD int map_intr {
1052 } DEFAULT bhnd_bus_null_map_intr;
1055 * Unmap an bus interrupt previously mapped via BHND_BUS_MAP_INTR().
1057 * @param dev The bhnd bus device.
1058 * @param child The requesting child device.
1059 * @param intr The interrupt number being unmapped. This is equivalent to the
1060 * bus resource ID for the interrupt.
1062 METHOD void unmap_intr {
1066 } DEFAULT bhnd_bus_null_unmap_intr;
1069 * Return true if @p region_num is a valid region on @p port_num of
1070 * @p type attached to @p child.
1072 * @param dev The device whose child is being examined.
1073 * @param child The child device.
1074 * @param type The port type being queried.
1075 * @param port_num The port number being queried.
1076 * @param region_num The region number being queried.
1078 METHOD bool is_region_valid {
1081 bhnd_port_type type;
1087 * Return the number of ports of type @p type attached to @p child.
1089 * @param dev The device whose child is being examined.
1090 * @param child The child device.
1091 * @param type The port type being queried.
1093 METHOD u_int get_port_count {
1096 bhnd_port_type type;
1100 * Return the number of memory regions mapped to @p child @p port of
1103 * @param dev The device whose child is being examined.
1104 * @param child The child device.
1105 * @param port The port number being queried.
1106 * @param type The port type being queried.
1108 METHOD u_int get_region_count {
1111 bhnd_port_type type;
1116 * Return the SYS_RES_MEMORY resource-ID for a port/region pair attached to
1119 * @param dev The bus device.
1120 * @param child The bhnd child.
1121 * @param port_type The port type.
1122 * @param port_num The index of the child interconnect port.
1123 * @param region_num The index of the port-mapped address region.
1125 * @retval -1 No such port/region found.
1127 METHOD int get_port_rid {
1130 bhnd_port_type port_type;
1133 } DEFAULT bhnd_bus_null_get_port_rid;
1137 * Decode a port / region pair on @p child defined by @p type and @p rid.
1139 * @param dev The bus device.
1140 * @param child The bhnd child.
1141 * @param type The resource type.
1142 * @param rid The resource ID.
1143 * @param[out] port_type The port's type.
1144 * @param[out] port The port identifier.
1145 * @param[out] region The identifier of the memory region on @p port.
1148 * @retval non-zero No matching type/rid found.
1150 METHOD int decode_port_rid {
1155 bhnd_port_type *port_type;
1158 } DEFAULT bhnd_bus_null_decode_port_rid;
1161 * Get the address and size of @p region on @p port.
1163 * @param dev The bus device.
1164 * @param child The bhnd child.
1165 * @param port_type The port type.
1166 * @param port The port identifier.
1167 * @param region The identifier of the memory region on @p port.
1168 * @param[out] region_addr The region's base address.
1169 * @param[out] region_size The region's size.
1172 * @retval non-zero No matching port/region found.
1174 METHOD int get_region_addr {
1177 bhnd_port_type port_type;
1180 bhnd_addr_t *region_addr;
1181 bhnd_size_t *region_size;
1182 } DEFAULT bhnd_bus_null_get_region_addr;
1185 * Read an NVRAM variable.
1187 * It is the responsibility of the bus to delegate this request to
1188 * the appropriate NVRAM child device, or to a parent bus implementation.
1190 * @param dev The bus device.
1191 * @param child The requesting device.
1192 * @param name The NVRAM variable name.
1193 * @param[out] buf On success, the requested value will be written
1194 * to this buffer. This argment may be NULL if
1195 * the value is not desired.
1196 * @param[in,out] size The capacity of @p buf. On success, will be set
1197 * to the actual size of the requested value.
1198 * @param type The data type to be written to @p buf.
1201 * @retval ENOENT The requested variable was not found.
1202 * @retval ENOMEM If @p buf is non-NULL and a buffer of @p size is too
1203 * small to hold the requested value.
1204 * @retval ENODEV No valid NVRAM source could be found.
1205 * @retval EFTYPE If the @p name's data type cannot be coerced to @p type.
1206 * @retval ERANGE If value coercion would overflow @p type.
1207 * @retval non-zero If reading @p name otherwise fails, a regular unix
1208 * error code will be returned.
1210 METHOD int get_nvram_var {
1216 bhnd_nvram_type type;
1217 } DEFAULT bhnd_bus_null_get_nvram_var;
1220 /** An implementation of bus_read_1() compatible with bhnd_resource */
1221 METHOD uint8_t read_1 {
1224 struct bhnd_resource *r;
1228 /** An implementation of bus_read_2() compatible with bhnd_resource */
1229 METHOD uint16_t read_2 {
1232 struct bhnd_resource *r;
1236 /** An implementation of bus_read_4() compatible with bhnd_resource */
1237 METHOD uint32_t read_4 {
1240 struct bhnd_resource *r;
1244 /** An implementation of bus_write_1() compatible with bhnd_resource */
1245 METHOD void write_1 {
1248 struct bhnd_resource *r;
1253 /** An implementation of bus_write_2() compatible with bhnd_resource */
1254 METHOD void write_2 {
1257 struct bhnd_resource *r;
1262 /** An implementation of bus_write_4() compatible with bhnd_resource */
1263 METHOD void write_4 {
1266 struct bhnd_resource *r;
1271 /** An implementation of bus_read_stream_1() compatible with bhnd_resource */
1272 METHOD uint8_t read_stream_1 {
1275 struct bhnd_resource *r;
1279 /** An implementation of bus_read_stream_2() compatible with bhnd_resource */
1280 METHOD uint16_t read_stream_2 {
1283 struct bhnd_resource *r;
1287 /** An implementation of bus_read_stream_4() compatible with bhnd_resource */
1288 METHOD uint32_t read_stream_4 {
1291 struct bhnd_resource *r;
1295 /** An implementation of bus_write_stream_1() compatible with bhnd_resource */
1296 METHOD void write_stream_1 {
1299 struct bhnd_resource *r;
1304 /** An implementation of bus_write_stream_2() compatible with bhnd_resource */
1305 METHOD void write_stream_2 {
1308 struct bhnd_resource *r;
1313 /** An implementation of bus_write_stream_4() compatible with bhnd_resource */
1314 METHOD void write_stream_4 {
1317 struct bhnd_resource *r;
1322 /** An implementation of bus_read_multi_1() compatible with bhnd_resource */
1323 METHOD void read_multi_1 {
1326 struct bhnd_resource *r;
1332 /** An implementation of bus_read_multi_2() compatible with bhnd_resource */
1333 METHOD void read_multi_2 {
1336 struct bhnd_resource *r;
1342 /** An implementation of bus_read_multi_4() compatible with bhnd_resource */
1343 METHOD void read_multi_4 {
1346 struct bhnd_resource *r;
1352 /** An implementation of bus_write_multi_1() compatible with bhnd_resource */
1353 METHOD void write_multi_1 {
1356 struct bhnd_resource *r;
1362 /** An implementation of bus_write_multi_2() compatible with bhnd_resource */
1363 METHOD void write_multi_2 {
1366 struct bhnd_resource *r;
1372 /** An implementation of bus_write_multi_4() compatible with bhnd_resource */
1373 METHOD void write_multi_4 {
1376 struct bhnd_resource *r;
1382 /** An implementation of bus_read_multi_stream_1() compatible
1384 METHOD void read_multi_stream_1 {
1387 struct bhnd_resource *r;
1393 /** An implementation of bus_read_multi_stream_2() compatible
1395 METHOD void read_multi_stream_2 {
1398 struct bhnd_resource *r;
1404 /** An implementation of bus_read_multi_stream_4() compatible
1406 METHOD void read_multi_stream_4 {
1409 struct bhnd_resource *r;
1415 /** An implementation of bus_write_multi_stream_1() compatible
1417 METHOD void write_multi_stream_1 {
1420 struct bhnd_resource *r;
1426 /** An implementation of bus_write_multi_stream_2() compatible with
1428 METHOD void write_multi_stream_2 {
1431 struct bhnd_resource *r;
1437 /** An implementation of bus_write_multi_stream_4() compatible with
1439 METHOD void write_multi_stream_4 {
1442 struct bhnd_resource *r;
1448 /** An implementation of bus_set_multi_1() compatible with bhnd_resource */
1449 METHOD void set_multi_1 {
1452 struct bhnd_resource *r;
1458 /** An implementation of bus_set_multi_2() compatible with bhnd_resource */
1459 METHOD void set_multi_2 {
1462 struct bhnd_resource *r;
1468 /** An implementation of bus_set_multi_4() compatible with bhnd_resource */
1469 METHOD void set_multi_4 {
1472 struct bhnd_resource *r;
1478 /** An implementation of bus_set_region_1() compatible with bhnd_resource */
1479 METHOD void set_region_1 {
1482 struct bhnd_resource *r;
1488 /** An implementation of bus_set_region_2() compatible with bhnd_resource */
1489 METHOD void set_region_2 {
1492 struct bhnd_resource *r;
1498 /** An implementation of bus_set_region_4() compatible with bhnd_resource */
1499 METHOD void set_region_4 {
1502 struct bhnd_resource *r;
1508 /** An implementation of bus_read_region_1() compatible with bhnd_resource */
1509 METHOD void read_region_1 {
1512 struct bhnd_resource *r;
1518 /** An implementation of bus_read_region_2() compatible with bhnd_resource */
1519 METHOD void read_region_2 {
1522 struct bhnd_resource *r;
1528 /** An implementation of bus_read_region_4() compatible with bhnd_resource */
1529 METHOD void read_region_4 {
1532 struct bhnd_resource *r;
1538 /** An implementation of bus_read_region_stream_1() compatible with
1540 METHOD void read_region_stream_1 {
1543 struct bhnd_resource *r;
1549 /** An implementation of bus_read_region_stream_2() compatible with
1551 METHOD void read_region_stream_2 {
1554 struct bhnd_resource *r;
1560 /** An implementation of bus_read_region_stream_4() compatible with
1562 METHOD void read_region_stream_4 {
1565 struct bhnd_resource *r;
1571 /** An implementation of bus_write_region_1() compatible with bhnd_resource */
1572 METHOD void write_region_1 {
1575 struct bhnd_resource *r;
1581 /** An implementation of bus_write_region_2() compatible with bhnd_resource */
1582 METHOD void write_region_2 {
1585 struct bhnd_resource *r;
1591 /** An implementation of bus_write_region_4() compatible with bhnd_resource */
1592 METHOD void write_region_4 {
1595 struct bhnd_resource *r;
1601 /** An implementation of bus_write_region_stream_1() compatible with
1603 METHOD void write_region_stream_1 {
1606 struct bhnd_resource *r;
1612 /** An implementation of bus_write_region_stream_2() compatible with
1614 METHOD void write_region_stream_2 {
1617 struct bhnd_resource *r;
1623 /** An implementation of bus_write_region_stream_4() compatible with
1625 METHOD void write_region_stream_4 {
1628 struct bhnd_resource *r;
1634 /** An implementation of bus_barrier() compatible with bhnd_resource */
1635 METHOD void barrier {
1638 struct bhnd_resource *r;