Manual Pages  — BHND

bhnd – BHND driver programming interface

SYNOPSIS Bus Resource Functions Bus Space Functions Device Configuration Functions Device Information Functions Device Matching Functions Device Table Functions DMA Address Translation Functions Interrupt Functions NVRAM Functions Port/Region Functions Power Management Functions Service Provider Functions Utility Functions DESCRIPTION Bus Resource Functions Bus Space Functions Device Configuration Functions Device Information Functions Device Matching Functions Device Table Functions DMA Address Translation Functions Interrupt Functions NVRAM Functions Port/Region Functions Power Management Functions Service Provider Functions Utility Functions RETURN VALUES Bus Resource Functions Device Configuration Functions Device Information Functions DMA Address Translation Functions Interrupt Functions NVRAM Functions Port/Region Functions PMU Functions Service Provider Functions Utility Functions SEE ALSO AUTHORS

#include <dev/bhnd/bhnd.h>

int
bhnd_activate_resource(device_t dev, int type, int rid, struct bhnd_resource *r);

struct bhnd_resource *
bhnd_alloc_resource(device_t dev, int type, int *rid, rman_res_t start, rman_res_t end, rman_res_t count, u_int flags);

struct bhnd_resource *
bhnd_alloc_resource_any(device_t dev, int type, int *rid, u_int flags);

int
bhnd_alloc_resources(device_t dev, struct resource_spec *rs, struct bhnd_resource **res);

int
bhnd_deactivate_resource(device_t dev, int type, int rid, struct bhnd_resource *r);

int
bhnd_release_resource(device_t dev, int type, int rid, struct bhnd_resource *r);

void
bhnd_release_resources(device_t dev, const struct resource_spec *rs, struct bhnd_resource **res);

void
bhnd_bus_barrier(struct bhnd_resource *r, bus_size_t offset, bus_size_t length, int flags);

uint8_t
bhnd_bus_read_1(struct bhnd_resource *r, bus_size_t offset);

uint16_t
bhnd_bus_read_2(struct bhnd_resource *r, bus_size_t offset);

uint32_t
bhnd_bus_read_4(struct bhnd_resource *r, bus_size_t offset);

void
bhnd_bus_read_multi_1(struct bhnd_resource *r, bus_size_t offset, uint8_t *datap, bus_size_t count);

void
bhnd_bus_read_multi_2(struct bhnd_resource *r, bus_size_t offset, uint16_t *datap, bus_size_t count);

void
bhnd_bus_read_multi_4(struct bhnd_resource *r, bus_size_t offset, uint32_t *datap, bus_size_t count);

void
bhnd_bus_read_multi_stream_1(struct bhnd_resource *r, bus_size_t offset, uint8_t *datap, bus_size_t count);

void
bhnd_bus_read_multi_stream_2(struct bhnd_resource *r, bus_size_t offset, uint16_t *datap, bus_size_t count);

void
bhnd_bus_read_multi_stream_4(struct bhnd_resource *r, bus_size_t offset, uint32_t *datap, bus_size_t count);

void
bhnd_bus_read_region_1(struct bhnd_resource *r, bus_size_t offset, uint8_t *datap, bus_size_t count);

void
bhnd_bus_read_region_2(struct bhnd_resource *r, bus_size_t offset, uint16_t *datap, bus_size_t count);

void
bhnd_bus_read_region_4(struct bhnd_resource *r, bus_size_t offset, uint32_t *datap, bus_size_t count);

void
bhnd_bus_read_region_stream_1(struct bhnd_resource *r, bus_size_t offset, uint8_t *datap, bus_size_t count);

void
bhnd_bus_read_region_stream_2(struct bhnd_resource *r, bus_size_t offset, uint16_t *datap, bus_size_t count);

void
bhnd_bus_read_region_stream_4(struct bhnd_resource *r, bus_size_t offset, uint32_t *datap, bus_size_t count);

void
bhnd_bus_read_stream_1(struct bhnd_resource *r, bus_size_t offset);

void
bhnd_bus_read_stream_2(struct bhnd_resource *r, bus_size_t offset);

uint32_t
bhnd_bus_read_stream_4(struct bhnd_resource *r, bus_size_t offset);

void
bhnd_bus_set_multi_1(struct bhnd_resource *r, bus_size_t offset, uint8_t value, bus_size_t count);

void
bhnd_bus_set_multi_2(struct bhnd_resource *r, bus_size_t offset, uint16_t value, bus_size_t count);

void
bhnd_bus_set_multi_4(struct bhnd_resource *r, bus_size_t offset, uint32_t value, bus_size_t count);

void
bhnd_bus_set_region_1(struct bhnd_resource *r, bus_size_t offset, uint8_t value, bus_size_t count);

void
bhnd_bus_set_region_2(struct bhnd_resource *r, bus_size_t offset, uint16_t value, bus_size_t count);

void
bhnd_bus_set_region_4(struct bhnd_resource *r, bus_size_t offset, uint32_t value, bus_size_t count);

void
bhnd_bus_write_1(struct bhnd_resource *r, uint8_t value);

void
bhnd_bus_write_2(struct bhnd_resource *r, uint16_t value);

void
bhnd_bus_write_4(struct bhnd_resource *r, uint32_t value);

void
bhnd_bus_write_multi_1(struct bhnd_resource *r, bus_size_t offset, uint8_t *datap, bus_size_t count);

void
bhnd_bus_write_multi_2(struct bhnd_resource *r, bus_size_t offset, uint16_t *datap, bus_size_t count);

void
bhnd_bus_write_multi_4(struct bhnd_resource *r, bus_size_t offset, uint32_t *datap, bus_size_t count);

void
bhnd_bus_write_multi_stream_1(struct bhnd_resource *r, bus_size_t offset, uint8_t *datap, bus_size_t count);

void
bhnd_bus_write_multi_stream_2(struct bhnd_resource *r, bus_size_t offset, uint16_t *datap, bus_size_t count);

void
bhnd_bus_write_multi_stream_4(struct bhnd_resource *r, bus_size_t offset, uint32_t *datap, bus_size_t count);

void
bhnd_bus_write_region_1(struct bhnd_resource *r, bus_size_t offset, uint8_t *datap, bus_size_t count);

void
bhnd_bus_write_region_2(struct bhnd_resource *r, bus_size_t offset, uint16_t *datap, bus_size_t count);

void
bhnd_bus_write_region_4(struct bhnd_resource *r, bus_size_t offset, uint32_t *datap, bus_size_t count);

void
bhnd_bus_write_region_stream_1(struct bhnd_resource *r, bus_size_t offset, uint8_t *datap, bus_size_t count);

void
bhnd_bus_write_region_stream_2(struct bhnd_resource *r, bus_size_t offset, uint16_t *datap, bus_size_t count);

void
bhnd_bus_write_region_stream_4(struct bhnd_resource *r, bus_size_t offset, uint32_t *datap, bus_size_t count);

void
bhnd_bus_write_stream_1(struct bhnd_resource *r, uint8_t value);

void
bhnd_bus_write_stream_2(struct bhnd_resource *r, uint16_t value);

void
bhnd_bus_write_stream_4(struct bhnd_resource *r, uint32_t value);

int
bhnd_read_ioctl(device_t dev, uint16_t *ioctl);

int
bhnd_write_ioctl(device_t dev, uint16_t value, uint16_t mask);

int
bhnd_read_iost(device_t dev, uint16_t *iost);

uint32_t
bhnd_read_config(device_t dev, bus_size_t offset, void *value, u_int width);

int
bhnd_write_config(device_t dev, bus_size_t offset, const void *value, u_int width);

int
bhnd_reset_hw(device_t dev, uint16_t ioctl, uint16_t reset_ioctl);

int
bhnd_suspend_hw(device_t dev, uint16_t ioctl);

bool
bhnd_is_hw_suspended(device_t dev);

bhnd_attach_type
bhnd_get_attach_type(device_t dev);

const struct bhnd_chipid *
bhnd_get_chipid(device_t dev);

bhnd_devclass_t
bhnd_get_class(device_t dev);

u_int
bhnd_get_core_index(device_t dev);

struct bhnd_core_info
bhnd_get_core_info(device_t dev);

int
bhnd_get_core_unit(device_t dev);

uint16_t
bhnd_get_device(device_t dev);

const char *
bhnd_get_device_name(device_t dev);

uint8_t
bhnd_get_hwrev(device_t dev);

uint16_t
bhnd_get_vendor(device_t dev);

const char *
bhnd_get_vendor_name(device_t dev);

int
bhnd_read_board_info(device_t dev, struct bhnd_board_info *info);

bool
bhnd_board_matches(const struct bhnd_board_info *board, const struct bhnd_board_match *desc);

device_t
bhnd_bus_match_child(device_t bus, const struct bhnd_core_match *desc);

bool
bhnd_chip_matches(const struct bhnd_chipid *chip, const struct bhnd_chip_match *desc);

struct bhnd_core_match
bhnd_core_get_match_desc(const struct bhnd_core_info *core);

bool
bhnd_core_matches(const struct bhnd_core_info *core, const struct bhnd_core_match *desc);

bool
bhnd_cores_equal(const struct bhnd_core_info *lhs, const struct bhnd_core_info *rhs);

bool
bhnd_hwrev_matches(uint16_t hwrev, const struct bhnd_hwrev_match *desc);

const struct bhnd_core_info *
bhnd_match_core(const struct bhnd_core_info *cores, u_int num_cores, const struct bhnd_core_match *desc);

const struct bhnd_device *
bhnd_device_lookup(device_t dev, const struct bhnd_device *table, size_t entry_size);

bool
bhnd_device_matches(device_t dev, const struct bhnd_device_match *desc);

uint32_t
bhnd_device_quirks(device_t dev, const struct bhnd_device *table, size_t entry_size);

BHND_BOARD_QUIRK(board, flags);

BHND_CHIP_QUIRK(chip, hwrev, flags);

BHND_CORE_QUIRK(hwrev, flags);

BHND_DEVICE(vendor, device, desc, quirks, ...);

BHND_DEVICE_IS_END(struct bhnd_device *d);

BHND_DEVICE_QUIRK_IS_END(struct bhnd_device_quirk *q);

BHND_PKG_QUIRK(chip, pkg, flags);

struct bhnd_device_quirk {
        struct bhnd_device_match        desc;
        uint32_t                        quirks;
};

struct bhnd_device {
    const struct bhnd_device_match       core;
    const char                          *desc;
    const struct bhnd_device_quirk      *quirks_table;
    uint32_t                             device_flags;
};

enum {
        BHND_DF_ANY     = 0,
        BHND_DF_HOSTB   = (1 << 0),
        BHND_DF_SOC     = (1 << 1),
        BHND_DF_ADAPTER = (1 << 2)
};

#define BHND_DEVICE_END { { BHND_MATCH_ANY }, NULL, NULL, 0 }

#define BHND_DEVICE_QUIRK_END { { BHND_MATCH_ANY }, 0 }

int
bhnd_get_dma_translation(device_t dev, u_int width, uint32_t flags, bus_dma_tag_t *dmat, struct bhnd_dma_translation *translation);

struct bhnd_dma_translation {
        bhnd_addr_t     base_addr;
        bhnd_addr_t     addr_mask;
        bhnd_addr_t     addrext_mask;
        uint32_t        flags;
};

typedef enum {
        BHND_DMA_ADDR_30BIT     = 30,
        BHND_DMA_ADDR_32BIT     = 32,
        BHND_DMA_ADDR_64BIT     = 64
} bhnd_dma_addrwidth;

enum bhnd_dma_translation_flags {
        BHND_DMA_TRANSLATION_PHYSMAP            = (1<<0),
        BHND_DMA_TRANSLATION_BYTESWAPPED        = (1<<1)
};

u_int
bhnd_get_intr_count(device_t dev);

int
bhnd_get_intr_ivec(device_t dev, u_int intr, u_int *ivec);

int
bhnd_map_intr(device_t dev, u_int intr, rman_res_t *irq);

void
bhnd_unmap_intr(device_t dev, rman_res_t irq);

int
bhnd_nvram_getvar(device_t dev, const char *name, void *buf, size_t *len, bhnd_nvram_type type);

int
bhnd_nvram_getvar_array(device_t dev, const char *name, void *buf, size_t size, bhnd_nvram_type type);

int
bhnd_nvram_getvar_int(device_t dev, const char *name, void *value, int width);

int
bhnd_nvram_getvar_int8(device_t dev, const char *name, int8_t *value);

int
bhnd_nvram_getvar_int16(device_t dev, const char *name, int16_t *value);

int
bhnd_nvram_getvar_int32(device_t dev, const char *name, int32_t *value);

int
bhnd_nvram_getvar_uint(device_t dev, const char *name, void *value, int width);

int
bhnd_nvram_getvar_uint8(device_t dev, const char *name, uint8_t *value);

int
bhnd_nvram_getvar_uint16(device_t dev, const char *name, uint16_t *value);

int
bhnd_nvram_getvar_uint32(device_t dev, const char *name, uint32_t *value);

int
bhnd_nvram_getvar_str(device_t dev, const char *name, char *buf, size_t len, size_t *rlen);

const char *
bhnd_nvram_string_array_next(const char *inp, size_t ilen, const char *prev, size_t *olen);

typedef enum {
        BHND_NVRAM_TYPE_UINT8           = 0,
        BHND_NVRAM_TYPE_UINT16          = 1,
        BHND_NVRAM_TYPE_UINT32          = 2,
        BHND_NVRAM_TYPE_UINT64          = 3,
        BHND_NVRAM_TYPE_INT8            = 4,
        BHND_NVRAM_TYPE_INT16           = 5,
        BHND_NVRAM_TYPE_INT32           = 6,
        BHND_NVRAM_TYPE_INT64           = 7,
        BHND_NVRAM_TYPE_CHAR            = 8,
        BHND_NVRAM_TYPE_STRING          = 9,
        BHND_NVRAM_TYPE_BOOL            = 10,
        BHND_NVRAM_TYPE_NULL            = 11,
        BHND_NVRAM_TYPE_DATA            = 12
        BHND_NVRAM_TYPE_UINT8_ARRAY     = 16,
        BHND_NVRAM_TYPE_UINT16_ARRAY    = 17,
        BHND_NVRAM_TYPE_UINT32_ARRAY    = 18,
        BHND_NVRAM_TYPE_UINT64_ARRAY    = 19,
        BHND_NVRAM_TYPE_INT8_ARRAY      = 20,
        BHND_NVRAM_TYPE_INT16_ARRAY     = 21,
        BHND_NVRAM_TYPE_INT32_ARRAY     = 22,
        BHND_NVRAM_TYPE_INT64_ARRAY     = 23,
        BHND_NVRAM_TYPE_CHAR_ARRAY      = 24,
        BHND_NVRAM_TYPE_STRING_ARRAY    = 25,
        BHND_NVRAM_TYPE_BOOL_ARRAY      = 26
} bhnd_nvram_type;

int
bhnd_decode_port_rid(device_t dev, int type, int rid, bhnd_port_type *port_type, u_int *port, u_int *region);

u_int
bhnd_get_port_count(device_t dev, bhnd_port_type type);

int
bhnd_get_port_rid(device_t dev, bhnd_port_type type, u_int port, u_int region);

int
bhnd_get_region_addr(device_t dev, bhnd_port_type port_type, u_int port, u_int region, bhnd_addr_t *region_addr, bhnd_size_t *region_size);

u_int
bhnd_get_region_count(device_t dev, bhnd_port_type type, u_int port);

bool
bhnd_is_region_valid(device_t dev, bhnd_port_type type, u_int port, u_int region);

typedef enum {
        BHND_PORT_DEVICE        = 0,
        BHND_PORT_BRIDGE        = 1,
        BHND_PORT_AGENT         = 2
} bhnd_port_type;

int
bhnd_alloc_pmu(device_t dev);

int
bhnd_release_pmu(device_t dev);

int
bhnd_enable_clocks(device_t dev, uint32_t clocks);

int
bhnd_request_clock(device_t dev, bhnd_clock clock);

int
bhnd_get_clock_freq(device_t dev, bhnd_clock clock, u_int *freq);

int
bhnd_get_clock_latency(device_t dev, bhnd_clock clock, u_int *latency);

int
bhnd_request_ext_rsrc(device_t dev, u_int rsrc);

int
bhnd_release_ext_rsrc(device_t dev, u_int rsrc);

typedef enum {
        BHND_CLOCK_DYN  = (1 << 0),
        BHND_CLOCK_ILP  = (1 << 1),
        BHND_CLOCK_ALP  = (1 << 2),
        BHND_CLOCK_HT   = (1 << 3)
} bhnd_clock;

int
bhnd_register_provider(device_t dev, bhnd_service_t service);

int
bhnd_deregister_provider(device_t dev, bhnd_service_t service);

device_t
bhnd_retain_provider(device_t dev, bhnd_service_t service);

void
bhnd_release_provider(device_t dev, device_t provider, bhnd_service_t service);

typedef enum {
        BHND_SERVICE_CHIPC,
        BHND_SERVICE_PWRCTL,
        BHND_SERVICE_PMU,
        BHND_SERVICE_NVRAM,
        BHND_SERVICE_GPIO,
        BHND_SERVICE_ANY        = 1000
} bhnd_service_t;

bhnd_erom_class_t *
bhnd_driver_get_erom_class(driver_t *driver);

bhnd_devclass_t
bhnd_find_core_class(uint16_t vendor, uint16_t device);

const char *
bhnd_find_core_name(uint16_t vendor, uint16_t device);

bhnd_devclass_t
bhnd_core_class(const struct bhnd_core_info *ci);

const char *
bhnd_core_name(const struct bhnd_core_info *ci);

int
bhnd_format_chip_id(char *buffer, size_t size, uint16_t chip_id);

void
bhnd_set_custom_core_desc(device_t dev, const char *dev_name);

void
bhnd_set_default_core_desc(device_t dev);

const char *
bhnd_vendor_name(uint16_t vendor);

#define BHND_CHIPID_MAX_NAMELEN 32

The bhnd_read_ioctl() function is used to read the I/O control register value of device dev, returning the current value in ioctl.

The bhnd_write_ioctl() function is used to modify the I/O control register of dev. The new value of the register is computed by updating any bits set in mask to value. The following I/O control flags are supported:

BHND_IOCTL_BIST	Initiate a built-in self-test (BIST). Must be cleared after BIST results are read via the IOST (I/O Status) register.
BHND_IOCTL_PME	Enable posting of power management events by the core.
BHND_IOCTL_CLK_FORCE
	Force disable of clock gating, resulting in all clocks being distributed within the core. Should be set when asserting/deasserting reset to ensure the reset signal fully propagates to the entire core.
BHND_IOCTL_CLK_EN	If cleared, the core clock will be disabled. Should be set during normal operation, and cleared when the core is held in reset.
BHND_IOCTL_CFLAGS	The mask of IOCTL bits reserved for additional core-specific I/O control flags.

The bhnd_read_iost() function is used to read the I/O status register of device dev, returning the current value in iost. The following I/O status flags are supported:

BHND_IOST_BIST_DONE
	Set upon BIST completion. Will be cleared when the BHND_IOCTL_BIST flag of the I/O control register is cleared using bhnd_write_ioctl().
BHND_IOST_BIST_FAIL
	Set upon detection of a BIST error; the value is unspecified if BIST has not completed and BHND_IOST_BIST_DONE is not also set.
BHND_IOST_CLK	Set if the core has required that clocked be ungated, or cleared otherwise. The value is undefined if a core does not support clock gating.
BHND_IOST_DMA64	Set if this core supports 64-bit DMA.
BHND_IOST_CFLAGS	The mask of IOST bits reserved for additional core-specific I/O status flags.

The bhnd_read_config() function is used to read a data item of width bytes at offset from the backplane-specific agent/config space of the device dev.

The bhnd_write_config() function is used to write a data item of width bytes with value at offset from the backplane-specific agent/config space of the device dev. The requested width must be one of 1, 2, or 4 bytes.

The agent/config space accessible via bhnd_read_config() and bhnd_write_config() is backplane-specific, and these functions should only be used for functionality that is not available via another bhnd function.

The bhnd_suspend_hw() function transitions the device dev to a low power "RESET" state, writing ioctl to the I/O control flags of dev. The hardware may be brought out of this state using bhnd_reset_hw().

The bhnd_reset_hw() function first transitions the device dev to a low power RESET state, writing ioctl_reset to the I/O control flags of dev, and then brings the device out of RESET, writing ioctl to the device's I/O control flags.

The bhnd_is_hw_suspended() function returns true if the device dev is currently held in a RESET state, or is otherwise not clocked. Otherwise, it returns false.

Any outstanding per-device PMU requests made using bhnd_enable_clocks(), bhnd_request_clock(), or bhnd_request_ext_rsrc() will be released automatically upon placing a device into a RESET state.

The bhnd device matching functions are used to match against core, chip, and board-level device attributes. Match requirements are specified using the struct bhnd_board_match, struct bhnd_chip_match, struct bhnd_core_match, struct bhnd_device_match, and struct bhnd_hwrev_match match descriptor structures.

The bhnd_board_matches() function returns true if board matches the board match descriptor desc. Otherwise, it returns false.

The bhnd_chip_matches() function returns true if chip matches the chip match descriptor desc. Otherwise, it returns false.

The bhnd_core_matches() function returns true if core matches the core match descriptor desc. Otherwise, it returns false.

The bhnd_device_matches() function returns true if the device dev matches the device match descriptor desc. Otherwise, it returns false.

The bhnd_hwrev_matches() function returns true if hwrev matches the hwrev match descriptor desc. Otherwise, it returns false.

The bhnd_bus_match_child() function returns the first child device of bus that matches the device match descriptor desc. If no matching child is found, NULL is returned.

The bhnd_core_get_match_desc() function returns an equality match descriptor for the core info in core. The returned descriptor will match only on core attributes identical to those defined by core.

The bhnd_cores_equal() function is a convenience wrapper for bhnd_core_matches() and bhnd_core_get_match_desc(). This function returns true if the bhnd_core_info structures lhs and rhs are equal. Otherwise, it returns false.

The bhnd_match_core() function returns a pointer to the first entry in the array cores of length num_cores that matches desc. If no matching core is found, NULL is returned.

A bhnd_board_match match descriptor may be initialized using one or more of the following macros:

BHND_MATCH_BOARD_VENDOR(vendor)
	Match on boards with a vendor equal to vendor.
BHND_MATCH_BOARD_TYPE(type)
	Match on boards with a type equal to BHND_BOARD_ ## type
BHND_MATCH_SROMREV(sromrev)
	Match on boards with a sromrev that matches BHND_HWREV_ ## sromrev.
BHND_MATCH_BOARD_REV(hwrev)
	Match on boards with hardware revisions that match BHND_ ## hwrev.
BHND_MATCH_BOARD(vendor, type)
	A convenience wrapper for BHND_MATCH_BOARD_VENDOR() and BHND_MATCH_BOARD_TYPE().

For example:

struct bhnd_board_match board_desc = {
        BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM),
        BHND_MATCH_BOARD_TYPE(BCM94360X52C),
        BHND_MATCH_BOARD_REV(HWREV_ANY),
        BHND_MATCH_SROMREV(RANGE(0, 10))
};

A bhnd_chip_match match descriptor may be initialized using one or more of the following macros:

BHND_MATCH_CHIP_ID(id)
	Match on chips with an ID equal to BHND_CHIPID_ ## id
BHND_MATCH_CHIP_REV(hwrev)
	Match on chips with hardware revisions that match BHND_ ## hwrev.
BHND_MATCH_CHIP_PKG(pkg)
	Match on chips with a package ID equal to BHND_PKGID_ ## pkg
BHND_MATCH_CHIP_TYPE(type)
	Match on chips with a chip type equal to BHND_CHIPTYPE_ ## type
BHND_MATCH_CHIP_IP(id, pkg)
	A convenience wrapper for BHND_MATCH_CHIP_ID() and BHND_MATCH_CHIP_PKG().
BHND_MATCH_CHIP_IPR(id, pkg, hwrev)
	A convenience wrapper for BHND_MATCH_CHIP_ID(), BHND_MATCH_CHIP_PKG(), and BHND_MATCH_CHIP_REV().
BHND_MATCH_CHIP_IR(id, hwrev)
	A convenience wrapper for BHND_MATCH_CHIP_ID() and BHND_MATCH_CHIP_REV().

For example:

struct bhnd_chip_match chip_desc = {
        BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN),
        BHND_MATCH_CHIP_TYPE(SIBA)
};

A bhnd_core_match match descriptor may be initialized using one or more of the following macros:

BHND_MATCH_CORE_VENDOR(vendor)
	Match on cores with a vendor ID equal to vendor
BHND_MATCH_CORE_ID(id)
	Match on cores with a device ID equal to id
BHND_MATCH_CORE_REV(hwrev)
	Match on cores with hardware revisions that match BHND_ ## hwrev.
BHND_MATCH_CORE_CLASS(class)
	Match on cores with a core device class equal to class
BHND_MATCH_CORE_IDX(idx)
	Match on cores with a core index equal to idx
BHND_MATCH_CORE_UNIT(unit)
	Match on cores with a core unit equal to unit
BHND_MATCH_CORE(vendor, id)
	A convenience wrapper for BHND_MATCH_CORE_VENDOR() and BHND_MATCH_CORE_ID().

For example:

struct bhnd_core_match core_desc = {
        BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC),
        BHND_MATCH_CORE_REV(HWREV_RANGE(0, 10))
};

The bhnd_device_match match descriptor supports matching on all board, chip, and core attributes, and may be initialized using any of the bhnd_board_match, bhnd_chip_match, or bhnd_core_match macros.

For example:

struct bhnd_device_match device_desc = {
        BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN),
        BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM),
        BHND_MATCH_BOARD_TYPE(BCM94329AGB),
        BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC),
};

A bhnd_hwrev_match match descriptor may be initialized using one of the following macros:

BHND_HWREV_ANY	Matches any hardware revision.
BHND_HWREV_EQ(hwrev)
	Matches any hardware revision equal to hwrev
BHND_HWREV_GTE(hwrev)
	Matches any hardware revision greater than or equal to hwrev
BHND_HWREV_LTE(hwrev)
	Matches any hardware revision less than or equal to hwrev
BHND_HWREV_RANGE(start, end)
	Matches any hardware revision within an inclusive range. If BHND_HWREV_INVALID is specified as the end value, will match on any revision equal to or greater than start

The bhnd device table functions are used to query device and quirk tables.

The bhnd_device_lookup() function returns a pointer to the first entry in device table table that matches the device dev. The table entry size is specified by entry_size.

The bhnd_device_quirks() function scan the device table table for all quirk entries that match the device dev, returning the bitwise OR of all matching quirk flags. The table entry size is specified by entry_size.

The bhnd_device structure contains the following fields:

core
	A bhnd_device_match descriptor.
desc
	A verbose device description suitable for use with device_set_desc(9), or NULL.
quirks_table
	The quirks table for this device, or NULL.
device_flags
	The device flags required when matching this entry.

The following device flags are supported:

BHND_DF_ANY	Match on any device.
BHND_DF_HOSTB	Match only if the device is the bhndb(4) host bridge. Implies BHND_DF_ADAPTER.
BHND_DF_SOC	Match only if the device is attached to a native SoC backplane.
BHND_DF_ADAPTER
	Match only if the device is attached to a bhndb(4) bridged backplane.

A bhnd_device table entry may be initialized using one of the following macros:

BHND_DEVICE(vendor, device, desc, quirks, flags)	Match on devices with a vendor ID equal to BHND_MFGID_ ## vendor and a core device ID equal to BHND_COREID_ ## device. The device's verbose description is specified by the desc argument, a pointer to the device-specific quirks table is specified by the quirks argument, and any required device flags may be provided in flags. The optional flags argument defaults to BHND_DF_ANY if omitted.
BHND_DEVICE_END	Terminate the bhnd_device table.

For example:

struct bhnd_device bhnd_usb11_devices[] = {
        BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller",
            bhnd_usb11_quirks),
        BHND_DEVICE_END
};

The bhnd_device_quirk structure contains the following fields:

desc
	A bhnd_device_match descriptor.
quirks
	Applicable quirk flags.

A bhnd_device_quirk table entry may be initialized using one of the following convenience macros:

BHND_BOARD_QUIRK(board, flags)
	Set quirk flags flags on devices with a board type equal to BHND_BOARD_ ## board.
BHND_CHIP_QUIRK(chip, hwrev, flags)
	Set quirk flags flags on devices with a chip ID equal to BHND_CHIPID_BCM ## chip and chip hardware revision that matches BHND_ ## hwrev.
BHND_PKG_QUIRK(chip, pkg, flags")
	Set quirk flags flags on devices with a chip ID equal to BHND_CHIPID_BCM ## chip and chip package equal to BHND_ ## chip ## pkg.
BHND_CORE_QUIRK(hwrev, flags")
	Set quirk flags flags on devices with a core hardware revision that matches BHND_ ## hwrev.

For example:

struct bhnd_device_quirk bhnd_usb11_quirks[] = {
        BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller",
            bhnd_usb11_quirks),
        BHND_DEVICE_END
};

The bhnd_get_dma_translation() function is used to request a DMA address translation descriptor suitable for use with a maximum DMA address width of width, with support for the requested translation flags.

If a suitable DMA address translation descriptor is found, it will be stored in translation, and a bus DMA tag specifying the DMA translation's address restrictions will be stored in dmat. The translation and dmat arguments may be NULL if the translation descriptor or DMA tag are not desired.

The following DMA translation flags are supported:

BHND_DMA_TRANSLATION_PHYSMAP	The translation remaps the device's physical address space. This is used in conjunction with BHND_DMA_TRANSLATION_BYTESWAPPED to define a DMA translation that provides byteswapped access to physical memory on big-endian MIPS SoCs.
BHND_DMA_TRANSLATION_BYTESWAPPED
	The translation provides a byte-swapped mapping; write requests will be byte-swapped before being written to memory, and read requests will be byte-swapped before being returned. This is primarily used to perform efficient byte swapping of DMA data on embedded MIPS SoCs executing in big-endian mode.

The following symbolic constants are defined for common DMA address widths:

BHND_DMA_ADDR_30BIT
	30-bit DMA
BHND_DMA_ADDR_32BIT
	32-bit DMA
BHND_DMA_ADDR_64BIT
	64-bit DMA

The bhnd_dma_translation structure contains the following fields:

base_addr
	Host-to-device physical address translation. This may be added to a host physical address to produce a device DMA address.
addr_mask
	Device-addressable address mask. This defines the device DMA address range, and excludes any bits reserved for mapping the address within the translation window at base_addr.
addrext_mask
	Device-addressable extended address mask. If a the per-core BHND DMA engine supports the 'addrext' control field, it can be used to provide address bits excluded by addr_mask. Support for DMA extended address changes — including coordination with the core providing device-to-host DMA address translation — is handled transparently by the DMA engine. For example, on PCI Wi-Fi devices, the Wi-Fi core's DMA engine will (in effect) update the PCI host bridge core's DMA sbtopcitranslation base address to map the target address prior to performing a DMA transaction.
flags
	Translation flags.

The bhnd_get_intr_count() function is used to determine the number of backplane interrupt lines assigned to the device dev. Interrupt line identifiers are allocated in monotonically increasing order, starting with 0.

The bhnd_get_intr_ivec() function is used to determine the backplane interrupt vector assigned to interrupt line intr on the device dev, writing the result to ivec. Interrupt vector assignments are backplane-specific: On BCMA devices, this function returns the OOB bus line assigned to the interrupt. On SIBA devices, it returns the target OCP slave flag number assigned to the interrupt.

The bhnd_map_intr() function is used to map interrupt line intr assigned to device dev to an IRQ number, writing the result to irq. Until unmapped, this IRQ may be used when allocating a resource of type SYS_RES_IRQ.

Ownership of the interrupt mapping is assumed by the caller, and must be explicitly released using bhnd_unmap_intr.

The bhnd_unmap_intr() function is used to unmap bus IRQ irq previously mapped using bhnd_map_intr() by the device dev.

Per-device interconnect memory mappings are identified by a combination of port type, port number, and region number. Port and memory region identifiers are allocated in monotonically increasing order for each port type, starting with 0.

The following port types are supported:

BHND_PORT_DEVICE
	Device memory. The device's control/status registers are always mapped by the first device port and region, and will be assigned a SYS_RES_MEMORY resource ID of 0.
BHND_PORT_BRIDGE
	Bridge memory.
BHND_PORT_AGENT	Interconnect agent/wrapper.

The bhnd_decode_port_rid() function is used to decode the resource ID rid assigned to device dev, of resource type type, writing the port type to port_type, port number to port, and region number to region.

The bhnd_get_port_count() function returns the number of ports of type type assigned to device dev.

The bhnd_get_port_rid() function returns the resource ID for the SYS_RES_MEMORY resource mapping the port of type and region on device dev, or -1 if the port or region are invalid, or do not have an assigned resource ID.

The bhnd_get_region_addr() function is used to determine the base address and size of the memory region on port of type assigned to dev. The region's base device address will be written to region_addr, and the region size to region_size.

The bhnd_get_region_count() function returns the number of memory regions mapped to port of type on device dev.

The bhnd_is_region_valid() function returns true if region is a valid region mapped by port of type on device dev.

The bhnd_activate_resource(), bhnd_alloc_resources(), bhnd_deactivate_resource(), and bhnd_release_resource() functions return 0 on success, otherwise an appropriate error code is returned.

The bhnd_alloc_resource() and bhnd_alloc_resource_any() functions return a pointer to struct resource on success, a null pointer otherwise.

The bhnd_read_config() and bhnd_write_config() functions return 0 on success, or one of the following values on error:

[EINVAL]
	The device is not a direct child of the bhnd(4) bus
[EINVAL]
	The requested width is not one of 1, 2, or 4 bytes.
[ENODEV]
	Accessing agent/config space for the device is unsupported.
[EFAULT]
	The requested offset or width exceeds the bounds of the mapped agent/config space.

The bhnd_read_ioctl(), bhnd_write_ioctl(), bhnd_read_iost(), bhnd_reset_hw(), and bhnd_suspend_hw() functions return 0 on success, otherwise an appropriate error code is returned.

The bhnd_read_board_info() function returns 0 on success, otherwise an appropriate error code is returned.

The bhnd_get_dma_translation() function returns 0 on success, or one of the following values on error:

[ENODEV]
	DMA is not supported.
[ENOENT]
	No DMA translation matching the requested address width and translation flags is available.

If fetching the requested DMA address translation otherwise fails, an appropriate error code will be returned.

The bhnd_get_intr_ivec() function returns 0 on success, or ENXIO if the requested interrupt line exceeds the number of interrupt lines assigned to the device.

The bhnd_map_intr() function returns 0 on success, otherwise an appropriate error code is returned.

The bhnd_nvram_getvar(), bhnd_nvram_getvar_array(), bhnd_nvram_getvar_int(), bhnd_nvram_getvar_int8(), bhnd_nvram_getvar_int16(), bhnd_nvram_getvar_int32(), bhnd_nvram_getvar_uint(), bhnd_nvram_getvar_uint8(), bhnd_nvram_getvar_uint16(), and bhnd_nvram_getvar_uint32() functions return 0 on success, or one of the following values on error:

[ENODEV]
	If an NVRAM provider has not been registered with the bus.
[ENOENT]
	The requested variable was not found.
[ENOMEM]
	If the buffer of size is too small to hold the requested value.
[EOPNOTSUPP]
	If the value's native type is incompatible with and cannot be coerced to the requested type.
[ERANGE]
	If value coercion would overflow (or underflow) the requested type

If reading the variable otherwise fails, an appropriate error code will be returned.

The bhnd_decode_port_rid() function returns 0 on success, or an appropriate error code if no matching port/region is found.

The bhnd_get_port_rid() function returns the resource ID for the requested port and region, or -1 if the port or region are invalid, or do not have an assigned resource ID.

The bhnd_get_region_addr() function returns 0 on success, or an appropriate error code if no matching port/region is found.

The bhnd_alloc_pmu() function returns 0 on success, otherwise an appropriate error code is returned.

The bhnd_release_pmu() function returns 0 on success, otherwise an appropriate error code is returned, and the core state will be left unmodified.

The bhnd_enable_clocks() and bhnd_request_clock() functions return 0 on success, or one of the following values on error:

[ENODEV]
	An unsupported clock was requested.
[ENXIO]
	No PMU or PWRCTL provider has been registered with the bus.

The bhnd_get_clock_freq() function returns 0 on success, or ENODEV if the frequency for the specified clock is not available.

The bhnd_get_clock_latency() function returns 0 on success, or ENODEV if the transition latency for the specified clock is not available.

The bhnd_request_ext_rsrc() and bhnd_release_ext_rsrc() functions return 0 on success, otherwise an appropriate error code is returned.

The bhnd_register_provider() function returns 0 on success, EEXIST if an entry for service already exists, or an appropriate error code if service registration otherwise fails.

The bhnd_deregister_provider() function returns 0 on success, or EBUSY if active references to the service provider exist.

The bhnd_retain_provider() function returns a pointer to device_t on success, a null pointer if the requested provider is not registered.

The bhnd_format_chip_id() function returns the total number of bytes written on success, or a negative integer on failure.

The bhnd driver programming interface and this manual page were written by Landon Fuller <Mt landonf@FreeBSD.org>.