xref: /freebsd/share/man/man9/bhnd.9 (revision 56e53cb8ef000c3ef72337a4095987a932cdedef)
1.\" Copyright (c) 2015-2016 Landon Fuller <landonf@FreeBSD.org>
2.\" Copyright (c) 2017 The FreeBSD Foundation
3.\" All rights reserved.
4.\"
5.\" Portions of this documentation were written by Landon Fuller
6.\" under sponsorship from the FreeBSD Foundation.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
29.\" $FreeBSD$
30.\"
31.Dd January 19, 2018
32.Dt BHND 9
33.Os
34.Sh NAME
35.Nm bhnd
36.Nd BHND driver programming interface
37.Sh SYNOPSIS
38.In dev/bhnd/bhnd.h
39.\"
40.Ss Bus Resource Functions
41.Ft int
42.Fo bhnd_activate_resource
43.Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r"
44.Fc
45.Ft "struct bhnd_resource *"
46.Fo bhnd_alloc_resource
47.Fa "device_t dev" "int type" "int *rid" "rman_res_t start" "rman_res_t end"
48.Fa "rman_res_t count" "u_int flags"
49.Fc
50.Ft "struct bhnd_resource *"
51.Fo bhnd_alloc_resource_any
52.Fa "device_t dev" "int type" "int *rid" "u_int flags"
53.Fc
54.Ft int
55.Fo bhnd_alloc_resources
56.Fa "device_t dev" "struct resource_spec *rs" "struct bhnd_resource **res"
57.Fc
58.Ft int
59.Fo bhnd_deactivate_resource
60.Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r"
61.Fc
62.Ft int
63.Fo bhnd_release_resource
64.Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r"
65.Fc
66.Ft void
67.Fo bhnd_release_resources
68.Fa "device_t dev" "const struct resource_spec *rs"
69.Fa "struct bhnd_resource **res"
70.Fc
71.\"
72.Ss "Bus Space Functions"
73.Ft void
74.Fo bhnd_bus_barrier
75.Fa "struct bhnd_resource *r" "bus_size_t offset"
76.Fa "bus_size_t length" "int flags"
77.Fc
78.Ft uint8_t
79.Fn bhnd_bus_read_1 "struct bhnd_resource *r" "bus_size_t offset"
80.Ft uint16_t
81.Fn bhnd_bus_read_2 "struct bhnd_resource *r" "bus_size_t offset"
82.Ft uint32_t
83.Fn bhnd_bus_read_4 "struct bhnd_resource *r" "bus_size_t offset"
84.Ft void
85.Fo bhnd_bus_read_multi_1
86.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
87.Fa "bus_size_t count"
88.Fc
89.Ft void
90.Fo bhnd_bus_read_multi_2
91.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
92.Fa "bus_size_t count"
93.Fc
94.Ft void
95.Fo bhnd_bus_read_multi_4
96.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
97.Fa "bus_size_t count"
98.Fc
99.Ft void
100.Fo bhnd_bus_read_multi_stream_1
101.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
102.Fa "bus_size_t count"
103.Fc
104.Ft void
105.Fo bhnd_bus_read_multi_stream_2
106.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
107.Fa "bus_size_t count"
108.Fc
109.Ft void
110.Fo bhnd_bus_read_multi_stream_4
111.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
112.Fa "bus_size_t count"
113.Fc
114.Ft void
115.Fo bhnd_bus_read_region_1
116.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
117.Fa "bus_size_t count"
118.Fc
119.Ft void
120.Fo bhnd_bus_read_region_2
121.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
122.Fa "bus_size_t count"
123.Fc
124.Ft void
125.Fo bhnd_bus_read_region_4
126.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
127.Fa "bus_size_t count"
128.Fc
129.Ft void
130.Fo bhnd_bus_read_region_stream_1
131.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
132.Fa "bus_size_t count"
133.Fc
134.Ft void
135.Fo bhnd_bus_read_region_stream_2
136.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
137.Fa "bus_size_t count"
138.Fc
139.Ft void
140.Fo bhnd_bus_read_region_stream_4
141.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
142.Fa "bus_size_t count"
143.Fc
144.Ft void
145.Fn bhnd_bus_read_stream_1 "struct bhnd_resource *r" "bus_size_t offset"
146.Ft void
147.Fn bhnd_bus_read_stream_2 "struct bhnd_resource *r" "bus_size_t offset"
148.Ft uint32_t
149.Fn bhnd_bus_read_stream_4 "struct bhnd_resource *r" "bus_size_t offset"
150.Ft void
151.Fo bhnd_bus_set_multi_1
152.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t value"
153.Fa "bus_size_t count"
154.Fc
155.Ft void
156.Fo bhnd_bus_set_multi_2
157.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t value"
158.Fa "bus_size_t count"
159.Fc
160.Ft void
161.Fo bhnd_bus_set_multi_4
162.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t value"
163.Fa "bus_size_t count"
164.Fc
165.Ft void
166.Fo bhnd_bus_set_region_1
167.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t value"
168.Fa "bus_size_t count"
169.Fc
170.Ft void
171.Fo bhnd_bus_set_region_2
172.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t value"
173.Fa "bus_size_t count"
174.Fc
175.Ft void
176.Fo bhnd_bus_set_region_4
177.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t value"
178.Fa "bus_size_t count"
179.Fc
180.Ft void
181.Fn bhnd_bus_write_1 "struct bhnd_resource *r" "uint8_t value"
182.Ft void
183.Fn bhnd_bus_write_2 "struct bhnd_resource *r" "uint16_t value"
184.Ft void
185.Fn bhnd_bus_write_4 "struct bhnd_resource *r" "uint32_t value"
186.Ft void
187.Fo bhnd_bus_write_multi_1
188.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
189.Fa "bus_size_t count"
190.Fc
191.Ft void
192.Fo bhnd_bus_write_multi_2
193.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
194.Fa "bus_size_t count"
195.Fc
196.Ft void
197.Fo bhnd_bus_write_multi_4
198.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
199.Fa "bus_size_t count"
200.Fc
201.Ft void
202.Fo bhnd_bus_write_multi_stream_1
203.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
204.Fa "bus_size_t count"
205.Fc
206.Ft void
207.Fo bhnd_bus_write_multi_stream_2
208.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
209.Fa "bus_size_t count"
210.Fc
211.Ft void
212.Fo bhnd_bus_write_multi_stream_4
213.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
214.Fa "bus_size_t count"
215.Fc
216.Ft void
217.Fo bhnd_bus_write_region_1
218.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
219.Fa "bus_size_t count"
220.Fc
221.Ft void
222.Fo bhnd_bus_write_region_2
223.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
224.Fa "bus_size_t count"
225.Fc
226.Ft void
227.Fo bhnd_bus_write_region_4
228.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
229.Fa "bus_size_t count"
230.Fc
231.Ft void
232.Fo bhnd_bus_write_region_stream_1
233.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
234.Fa "bus_size_t count"
235.Fc
236.Ft void
237.Fo bhnd_bus_write_region_stream_2
238.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
239.Fa "bus_size_t count"
240.Fc
241.Ft void
242.Fo bhnd_bus_write_region_stream_4
243.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
244.Fa "bus_size_t count"
245.Fc
246.Ft void
247.Fn bhnd_bus_write_stream_1 "struct bhnd_resource *r" "uint8_t value"
248.Ft void
249.Fn bhnd_bus_write_stream_2 "struct bhnd_resource *r" "uint16_t value"
250.Ft void
251.Fn bhnd_bus_write_stream_4 "struct bhnd_resource *r" "uint32_t value"
252.\"
253.Ss "Device Configuration Functions"
254.Ft int
255.Fn bhnd_read_ioctl "device_t dev" "uint16_t *ioctl"
256.Ft int
257.Fn bhnd_write_ioctl "device_t dev" "uint16_t value" "uint16_t mask"
258.Ft int
259.Fn bhnd_read_iost "device_t dev" "uint16_t *iost"
260.Ft uint32_t
261.Fo bhnd_read_config
262.Fa "device_t dev" "bus_size_t offset" "void *value" "u_int width"
263.Fc
264.Ft int
265.Fo bhnd_write_config
266.Fa "device_t dev" "bus_size_t offset" "const void *value" "u_int width"
267.Fc
268.Ft int
269.Fn bhnd_reset_hw "device_t dev" "uint16_t ioctl" "uint16_t reset_ioctl"
270.Ft int
271.Fn bhnd_suspend_hw "device_t dev" "uint16_t ioctl"
272.Ft bool
273.Fn bhnd_is_hw_suspended "device_t dev"
274.\"
275.Ss "Device Information Functions"
276.Ft bhnd_attach_type
277.Fo bhnd_get_attach_type
278.Fa "device_t dev"
279.Fc
280.Ft "const struct bhnd_chipid *"
281.Fo bhnd_get_chipid
282.Fa "device_t dev"
283.Fc
284.Ft bhnd_devclass_t
285.Fo bhnd_get_class
286.Fa "device_t dev"
287.Fc
288.Ft u_int
289.Fo bhnd_get_core_index
290.Fa "device_t dev"
291.Fc
292.Ft "struct bhnd_core_info"
293.Fo bhnd_get_core_info
294.Fa "device_t dev"
295.Fc
296.Ft int
297.Fo bhnd_get_core_unit
298.Fa "device_t dev"
299.Fc
300.Ft uint16_t
301.Fo bhnd_get_device
302.Fa "device_t dev"
303.Fc
304.Ft const char *
305.Fo bhnd_get_device_name
306.Fa "device_t dev"
307.Fc
308.Ft uint8_t
309.Fo bhnd_get_hwrev
310.Fa "device_t dev"
311.Fc
312.Ft uint16_t
313.Fo bhnd_get_vendor
314.Fa "device_t dev"
315.Fc
316.Ft const char *
317.Fo bhnd_get_vendor_name
318.Fa "device_t dev"
319.Fc
320.Ft int
321.Fo bhnd_read_board_info
322.Fa "device_t dev" "struct bhnd_board_info *info"
323.Fc
324.\"
325.Ss "Device Matching Functions"
326.Ft bool
327.Fo bhnd_board_matches
328.Fa "const struct bhnd_board_info *board" "const struct bhnd_board_match *desc"
329.Fc
330.Ft device_t
331.Fo bhnd_bus_match_child
332.Fa "device_t bus" "const struct bhnd_core_match *desc"
333.Fc
334.Ft bool
335.Fo bhnd_chip_matches
336.Fa "const struct bhnd_chipid *chip" "const struct bhnd_chip_match *desc"
337.Fc
338.Ft "struct bhnd_core_match"
339.Fo bhnd_core_get_match_desc
340.Fa "const struct bhnd_core_info *core"
341.Fc
342.Ft bool
343.Fo bhnd_core_matches
344.Fa "const struct bhnd_core_info *core" "const struct bhnd_core_match *desc"
345.Fc
346.Ft bool
347.Fo bhnd_cores_equal
348.Fa "const struct bhnd_core_info *lhs" "const struct bhnd_core_info *rhs"
349.Fc
350.Ft bool
351.Fo bhnd_hwrev_matches
352.Fa "uint16_t hwrev" "const struct bhnd_hwrev_match *desc"
353.Fc
354.Ft "const struct bhnd_core_info *"
355.Fo bhnd_match_core
356.Fa "const struct bhnd_core_info *cores" "u_int num_cores"
357.Fa "const struct bhnd_core_match *desc"
358.Fc
359.\"
360.Ss "Device Table Functions"
361.Ft "const struct bhnd_device *"
362.Fo bhnd_device_lookup
363.Fa "device_t dev" "const struct bhnd_device *table" "size_t entry_size"
364.Fc
365.Ft bool
366.Fo bhnd_device_matches
367.Fa "device_t dev" "const struct bhnd_device_match *desc"
368.Fc
369.Ft uint32_t
370.Fo bhnd_device_quirks
371.Fa "device_t dev" "const struct bhnd_device *table" "size_t entry_size"
372.Fc
373.Fo BHND_BOARD_QUIRK
374.Fa "board" "flags"
375.Fc
376.Fo BHND_CHIP_QUIRK
377.Fa "chip" "hwrev" "flags"
378.Fc
379.Fo BHND_CORE_QUIRK
380.Fa "hwrev" "flags"
381.Fc
382.Fo BHND_DEVICE
383.Fa "vendor" "device" "desc" "quirks" "..."
384.Fc
385.Fo BHND_DEVICE_IS_END
386.Fa "struct bhnd_device *d"
387.Fc
388.Fo BHND_DEVICE_QUIRK_IS_END
389.Fa "struct bhnd_device_quirk *q"
390.Fc
391.Fo BHND_PKG_QUIRK
392.Fa "chip" "pkg" "flags"
393.Fc
394.Bd -literal
395struct bhnd_device_quirk {
396	struct bhnd_device_match	desc;
397	uint32_t			quirks;
398};
399.Ed
400.Bd -literal
401struct bhnd_device {
402    const struct bhnd_device_match	 core;
403    const char				*desc;
404    const struct bhnd_device_quirk	*quirks_table;
405    uint32_t				 device_flags;
406};
407.Ed
408.Bd -literal
409enum {
410	BHND_DF_ANY	= 0,
411	BHND_DF_HOSTB	= (1 << 0),
412	BHND_DF_SOC	= (1 << 1),
413	BHND_DF_ADAPTER	= (1 << 2)
414};
415.Ed
416.Bd -literal
417#define BHND_DEVICE_END { { BHND_MATCH_ANY }, NULL, NULL, 0 }
418.Ed
419.Bd -literal
420#define BHND_DEVICE_QUIRK_END { { BHND_MATCH_ANY }, 0 }
421.Ed
422.\"
423.Ss "DMA Address Translation Functions"
424.Ft int
425.Fo bhnd_get_dma_translation
426.Fa "device_t dev" "u_int width" "uint32_t flags" "bus_dma_tag_t *dmat"
427.Fa "struct bhnd_dma_translation *translation"
428.Fc
429.Bd -literal
430struct bhnd_dma_translation {
431	bhnd_addr_t	base_addr;
432	bhnd_addr_t	addr_mask;
433	bhnd_addr_t	addrext_mask;
434	uint32_t	flags;
435};
436.Ed
437.Bd -literal
438typedef enum {
439	BHND_DMA_ADDR_30BIT	= 30,
440	BHND_DMA_ADDR_32BIT	= 32,
441	BHND_DMA_ADDR_64BIT	= 64
442} bhnd_dma_addrwidth;
443.Ed
444.Bd -literal
445enum bhnd_dma_translation_flags {
446	BHND_DMA_TRANSLATION_PHYSMAP		= (1<<0),
447	BHND_DMA_TRANSLATION_BYTESWAPPED	= (1<<1)
448};
449.Ed
450.\"
451.Ss "Interrupt Functions"
452.Ft u_int
453.Fo bhnd_get_intr_count
454.Fa "device_t dev"
455.Fc
456.Ft int
457.Fo bhnd_get_intr_ivec
458.Fa "device_t dev" "u_int intr" "u_int *ivec"
459.Fc
460.Ft int
461.Fo bhnd_map_intr
462.Fa "device_t dev" "u_int intr" "rman_res_t *irq"
463.Fc
464.Ft void
465.Fo bhnd_unmap_intr
466.Fa "device_t dev" "rman_res_t irq"
467.Fc
468.\"
469.Ss "NVRAM Functions"
470.Ft int
471.Fo bhnd_nvram_getvar
472.Fa "device_t dev" "const char *name" "void *buf" "size_t *len"
473.Fa "bhnd_nvram_type type"
474.Fc
475.Ft int
476.Fo bhnd_nvram_getvar_array
477.Fa "device_t dev" "const char *name" "void *buf" "size_t size"
478.Fa "bhnd_nvram_type type"
479.Fc
480.Ft int
481.Fo bhnd_nvram_getvar_int
482.Fa "device_t dev" "const char *name" "void *value" "int width"
483.Fc
484.Ft int
485.Fn bhnd_nvram_getvar_int8 "device_t dev" "const char *name" "int8_t *value"
486.Ft int
487.Fn bhnd_nvram_getvar_int16 "device_t dev" "const char *name" "int16_t *value"
488.Ft int
489.Fn bhnd_nvram_getvar_int32 "device_t dev" "const char *name" "int32_t *value"
490.Ft int
491.Fo bhnd_nvram_getvar_uint
492.Fa "device_t dev" "const char *name" "void *value" "int width"
493.Fc
494.Ft int
495.Fo bhnd_nvram_getvar_uint8
496.Fa "device_t dev" "const char *name" "uint8_t *value"
497.Fc
498.Ft int
499.Fo bhnd_nvram_getvar_uint16
500.Fa "device_t dev" "const char *name" "uint16_t *value"
501.Fc
502.Ft int
503.Fo bhnd_nvram_getvar_uint32
504.Fa "device_t dev" "const char *name" "uint32_t *value"
505.Fc
506.Ft int
507.Fo bhnd_nvram_getvar_str
508.Fa "device_t dev" "const char *name" "char *buf" "size_t len" "size_t *rlen"
509.Fc
510.Ft "const char *"
511.Fo bhnd_nvram_string_array_next
512.Fa "const char *inp" "size_t ilen" "const char *prev" "size_t *olen"
513.Fc
514.Bd -literal
515typedef enum {
516	BHND_NVRAM_TYPE_UINT8		= 0,
517	BHND_NVRAM_TYPE_UINT16		= 1,
518	BHND_NVRAM_TYPE_UINT32		= 2,
519	BHND_NVRAM_TYPE_UINT64		= 3,
520	BHND_NVRAM_TYPE_INT8		= 4,
521	BHND_NVRAM_TYPE_INT16		= 5,
522	BHND_NVRAM_TYPE_INT32		= 6,
523	BHND_NVRAM_TYPE_INT64		= 7,
524	BHND_NVRAM_TYPE_CHAR		= 8,
525	BHND_NVRAM_TYPE_STRING		= 9,
526	BHND_NVRAM_TYPE_BOOL		= 10,
527	BHND_NVRAM_TYPE_NULL		= 11,
528	BHND_NVRAM_TYPE_DATA		= 12
529	BHND_NVRAM_TYPE_UINT8_ARRAY	= 16,
530	BHND_NVRAM_TYPE_UINT16_ARRAY	= 17,
531	BHND_NVRAM_TYPE_UINT32_ARRAY	= 18,
532	BHND_NVRAM_TYPE_UINT64_ARRAY	= 19,
533	BHND_NVRAM_TYPE_INT8_ARRAY	= 20,
534	BHND_NVRAM_TYPE_INT16_ARRAY	= 21,
535	BHND_NVRAM_TYPE_INT32_ARRAY	= 22,
536	BHND_NVRAM_TYPE_INT64_ARRAY	= 23,
537	BHND_NVRAM_TYPE_CHAR_ARRAY	= 24,
538	BHND_NVRAM_TYPE_STRING_ARRAY	= 25,
539	BHND_NVRAM_TYPE_BOOL_ARRAY	= 26
540} bhnd_nvram_type;
541.Ed
542.\"
543.Ss "Port/Region Functions"
544.Ft int
545.Fo bhnd_decode_port_rid
546.Fa "device_t dev" "int type" "int rid" "bhnd_port_type *port_type"
547.Fa "u_int *port" "u_int *region"
548.Fc
549.Ft u_int
550.Fo bhnd_get_port_count
551.Fa "device_t dev" "bhnd_port_type type"
552.Fc
553.Ft int
554.Fo bhnd_get_port_rid
555.Fa "device_t dev" "bhnd_port_type type" "u_int port" "u_int region"
556.Fc
557.Ft int
558.Fo bhnd_get_region_addr
559.Fa "device_t dev" "bhnd_port_type port_type" "u_int port" "u_int region"
560.Fa "bhnd_addr_t *region_addr" "bhnd_size_t *region_size"
561.Fc
562.Ft u_int
563.Fo bhnd_get_region_count
564.Fa "device_t dev" "bhnd_port_type type" "u_int port"
565.Fc
566.Ft bool
567.Fo bhnd_is_region_valid
568.Fa "device_t dev" "bhnd_port_type type" "u_int port" "u_int region"
569.Fc
570.Bd -literal
571typedef enum {
572	BHND_PORT_DEVICE	= 0,
573	BHND_PORT_BRIDGE	= 1,
574	BHND_PORT_AGENT		= 2
575} bhnd_port_type;
576.Ed
577.\"
578.Ss "Power Management Functions"
579.Ft int
580.Fo bhnd_alloc_pmu
581.Fa "device_t dev"
582.Fc
583.Ft int
584.Fo bhnd_release_pmu
585.Fa "device_t dev"
586.Fc
587.Ft int
588.Fo bhnd_enable_clocks
589.Fa "device_t dev" "uint32_t clocks"
590.Fc
591.Ft int
592.Fo bhnd_request_clock
593.Fa "device_t dev" "bhnd_clock clock"
594.Fc
595.Ft int
596.Fo bhnd_get_clock_freq
597.Fa "device_t dev" "bhnd_clock clock" "u_int *freq"
598.Fc
599.Ft int
600.Fo bhnd_get_clock_latency
601.Fa "device_t dev" "bhnd_clock clock" "u_int *latency"
602.Fc
603.Ft int
604.Fo bhnd_request_ext_rsrc
605.Fa "device_t dev" "u_int rsrc"
606.Fc
607.Ft int
608.Fo bhnd_release_ext_rsrc
609.Fa "device_t dev" "u_int rsrc"
610.Fc
611.Bd -literal
612typedef enum {
613	BHND_CLOCK_DYN	= (1 << 0),
614	BHND_CLOCK_ILP	= (1 << 1),
615	BHND_CLOCK_ALP	= (1 << 2),
616	BHND_CLOCK_HT	= (1 << 3)
617} bhnd_clock;
618.Ed
619.\"
620.Ss "Service Provider Functions"
621.Ft int
622.Fo bhnd_register_provider
623.Fa "device_t dev" "bhnd_service_t service"
624.Fc
625.Ft int
626.Fo bhnd_deregister_provider
627.Fa "device_t dev" "bhnd_service_t service"
628.Fc
629.Ft device_t
630.Fo bhnd_retain_provider
631.Fa "device_t dev" "bhnd_service_t service"
632.Fc
633.Ft void
634.Fo bhnd_release_provider
635.Fa "device_t dev" "device_t provider" "bhnd_service_t service"
636.Fc
637.Bd -literal
638typedef enum {
639	BHND_SERVICE_CHIPC,
640	BHND_SERVICE_PWRCTL,
641	BHND_SERVICE_PMU,
642	BHND_SERVICE_NVRAM,
643	BHND_SERVICE_GPIO,
644	BHND_SERVICE_ANY	= 1000
645} bhnd_service_t;
646.Ed
647.\"
648.Ss "Utility Functions"
649.Ft "bhnd_erom_class_t *"
650.Fo bhnd_driver_get_erom_class
651.Fa "driver_t *driver"
652.Fc
653.Ft bhnd_devclass_t
654.Fo bhnd_find_core_class
655.Fa "uint16_t vendor" "uint16_t device"
656.Fc
657.Ft "const char *"
658.Fo bhnd_find_core_name
659.Fa "uint16_t vendor" "uint16_t device"
660.Fc
661.Ft bhnd_devclass_t
662.Fo bhnd_core_class
663.Fa "const struct bhnd_core_info *ci"
664.Fc
665.Ft "const char *"
666.Fo bhnd_core_name
667.Fa "const struct bhnd_core_info *ci"
668.Fc
669.Ft int
670.Fo bhnd_format_chip_id
671.Fa "char *buffer" "size_t size" "uint16_t chip_id"
672.Fc
673.Ft void
674.Fo bhnd_set_custom_core_desc
675.Fa "device_t dev" "const char *dev_name"
676.Fc
677.Ft void
678.Fo bhnd_set_default_core_desc
679.Fa "device_t dev"
680.Fc
681.Ft "const char *"
682.Fo bhnd_vendor_name
683.Fa "uint16_t vendor"
684.Fc
685.Bd -literal
686#define	BHND_CHIPID_MAX_NAMELEN	32
687.Ed
688.\"
689.Sh DESCRIPTION
690.Nm
691provides a unified bus and driver programming interface for the
692on-chip interconnects and IP cores found in Broadcom Home Networking Division
693(BHND) devices.
694.Pp
695The BHND device family consists of MIPS/ARM SoCs (System On a Chip) and
696host-connected chipsets based on a common library of Broadcom IP cores,
697connected via one of two on-chip backplane (hardware bus) architectures.
698.Pp
699Hardware designed prior to 2009 used Broadcom's
700.Dq SSB
701backplane architecture, based on Sonics Silicon's interconnect IP.
702Each core on the Sonics backplane vends a 4 KiB register block, containing both
703device-specific CSRs, and SSB-specific per-core device management
704(enable/reset/etc) registers.
705.Pp
706Subsequent hardware is based on Broadcom's
707.Dq BCMA
708backplane, based on ARM's AMBA IP.
709The IP cores used in earlier SSB-based devices were adapted for compatibility
710with the new backplane, with additional
711.Dq wrapper
712cores providing per-core device management functions in place of the SSB
713per-core management registers.
714.Pp
715When BHND hardware is used as a host-connected peripheral (e.g., in a PCI Wi-Fi
716card), the on-chip peripheral controller core is configured to operate as
717an endpoint device, bridging access to the SoC hardware:
718.Pp
719.Bl -dash -offset indent
720.It
721Host access to SoC address space is provided via a set of register windows
722(e.g., a set of configurable windows into SoC address space mapped via PCI BARs)
723.It
724DMA is supported by the bridge core's sparse mapping of host address space into
725the backplane address space.
726These address regions may be used as a target for the on-chip DMA engine.
727.It
728Any backplane interrupt vectors routed to the bridge core may be mapped by the
729bridge to host interrupts (e.g., PCI INTx/MSI/MSI-X).
730.El
731.Pp
732The
733.Nm
734driver programming interface \(em and
735.Xr bhndb 4
736host bridge drivers \(em support the implementation of common drivers for
737Broadcom IP cores, whether attached via a BHND host bridge, or via the native
738SoC backplane.
739.\"
740.Ss "Bus Resource Functions"
741The bhnd_resource functions are wrappers for the standard
742.Vt "struct resource"
743bus APIs, providing support for
744.Vt SYS_RES_MEMORY
745resources that, on
746.Xr bhndb 4
747bridged chipsets, may require on-demand remapping of address windows
748prior to accessing bus memory.
749.Pp
750These functions are primarily used in the implementation of BHND platform device
751drivers that, on host-connected peripherals, must share a small set of register
752windows during initial setup and teardown.
753.Pp
754BHND peripherals are designed to not require register window remapping
755during normal operation, and most drivers may safely use the standard
756.Vt struct resource
757APIs directly.
758.Pp
759The
760.Fn bhnd_activate_resource
761function activates a previously allocated resource.
762.Pp
763The arguments are as follows:
764.Bl -tag -width indent
765.It Fa dev
766The device holding ownership of the allocated resource.
767.It Fa type
768The type of the resource.
769.It Fa rid
770The bus-specific handle that identifies the resource being activated.
771.It Fa r
772A pointer to the resource returned by
773.Fn bhnd_alloc_resource .
774.El
775.Pp
776The
777.Fn bhnd_alloc_resource
778function allocates a resource from a device's parent
779.Xr bhnd 4
780bus.
781.Pp
782The arguments are as follows:
783.Bl -tag -width indent
784.It Fa dev
785The device requesting resource ownership.
786.It Fa type
787The type of resource to allocate.
788This may be any type supported by the standard
789.Xr bus_alloc_resource 9
790function.
791.It Fa rid
792The bus-specific handle identifying the resource being allocated.
793.It Fa start
794The start address of the resource.
795.It Fa end
796The end address of the resource.
797.It Fa count
798The size of the resource.
799.It Fa flags
800The flags for the resource to be allocated.
801These may be any values supported by the standard
802.Xr bus_alloc_resource 9
803function.
804.El
805.Pp
806To request that the bus supply the resource's default
807.Fa start ,
808.Fa end ,
809and
810.Fa count
811values, pass
812.Fa start
813and
814.Fa end
815values of 0ul and ~0ul respectively, and a
816.Fa count
817of 1.
818.Pp
819The
820.Fn bhnd_alloc_resource_any
821function is a convenience wrapper for
822.Fn bhnd_alloc_resource ,
823using the resource's default
824.Fa start ,
825.Fa end ,
826and
827.Fa count
828values.
829.Pp
830The arguments are as follows:
831.Bl -tag -width indent
832.It Fa dev
833The device requesting resource ownership.
834.It Fa type
835The type of resource to allocate.
836This may be any type supported by the standard
837.Xr bus_alloc_resource 9
838function.
839.It Fa rid
840The bus-specific handle identifying the resource being allocated.
841.It Fa flags
842The flags for the resource to be allocated.
843These may be any values supported by the standard
844.Xr bus_alloc_resource 9
845function.
846.El
847.Pp
848The
849.Fn bhnd_alloc_resources
850function allocates resources defined in resource specification from a device's
851parent
852.Xr bhnd 4
853bus.
854.Pp
855The arguments are as follows:
856.Bl -tag -width indent
857.It Fa dev
858The device requesting ownership of the resources.
859.It Fa rs
860A standard bus resource specification. If all requested resources, are
861successfully allocated, this will be updated with the allocated resource
862identifiers.
863.It Fa res
864If all requested resources are successfully allocated, this will be populated
865with the allocated
866.Vt "struct bhnd_resource"
867instances.
868.El
869.Pp
870The
871.Fn bhnd_deactivate_resource
872function deactivates a resource previously activated by.
873.Fn bhnd_activate_resource .
874The arguments are as follows:
875.Bl -tag -width indent
876.It Fa dev
877The device holding ownership of the activated resource.
878.It Fa type
879The type of the resource.
880.It Fa rid
881The bus-specific handle identifying the resource.
882.It Fa r
883A pointer to the resource returned by bhnd_alloc_resource.
884.El
885.Pp
886The
887.Fn bhnd_release_resource
888function frees a resource previously returned by
889.Fn bhnd_alloc_resource .
890The arguments are as follows:
891.Bl -tag -width indent
892.It Fa dev
893The device holding ownership of the resource.
894.It Fa type
895The type of the resource.
896.It Fa rid
897The bus-specific handle identifying the resource.
898.It Fa r
899A pointer to the resource returned by bhnd_alloc_resource.
900.El
901.Pp
902The
903.Fn bhnd_release_resources
904function frees resources previously returned by
905.Fn bhnd_alloc_resources .
906The arguments are as follows:
907.Bl -tag -width indent
908.It Fa dev
909The device that owns the resources.
910.It Fa rs
911A standard bus resource specification previously initialized by
912.Fn bhnd_alloc_resources .
913.It Fa res
914The resources to be released.
915.El
916.Pp
917The
918.Vt bhnd_resource
919structure contains the following fields:
920.Bl -tag -width "direct"
921.It Fa res
922A pointer to the bus
923.Vt struct resource .
924.It Fa direct
925If true, the resource requires bus window remapping before it is MMIO
926accessible.
927.El
928.Pp
929.\"
930.Ss "Bus Space Functions"
931The bhnd_bus_space functions wrap their equivalent
932.Xr bus_space 9
933counterparts, and provide support for accessing bus memory via
934.Vt "struct bhnd_resource".
935.Pp
936.Bl -ohang -offset indent -compact
937.It Fn bhnd_bus_barrier
938.It Fn bhnd_bus_[read|write]_[1|2|4]
939.It Fn bhnd_bus_[read_multi|write_multi]_[1|2|4]
940.It Fn bhnd_bus_[read_multi_stream|write_multi_stream]_[1|2|4]
941.It Fn bhnd_bus_[read_region|write_region]_[1|2|4]
942.It Fn bhnd_bus_[read_region_stream|write_region_stream]_[1|2|4]
943.It Fn bhnd_bus_[read_stream|write_stream]_[1|2|4]
944.It Fn bhnd_bus_[set_multi|set_stream]_[1|2|4]
945.El
946.Pp
947Drivers that do not rely on
948.Vt "struct bhnd_resource"
949should use the standard
950.Vt struct resource
951and
952.Xr bus_space 9
953APIs directly.
954.\"
955.Ss "Device Configuration Functions"
956The
957.Fn bhnd_read_ioctl
958function is used to read the I/O control register value of device
959.Fa dev ,
960returning the current value in
961.Fa ioctl .
962.Pp
963The
964.Fn bhnd_write_ioctl
965function is used to modify the I/O control register of
966.Fa dev .
967The new value of the register is computed by updating any bits set in
968.Fa mask
969to
970.Fa value .
971The following I/O control flags are supported:
972.Bl -tag -width ".Dv BHND_IOCTL_CLK_FORCE" -offset indent
973.It Dv BHND_IOCTL_BIST
974Initiate a built-in self-test (BIST).
975Must be cleared after BIST results are read via the IOST (I/O Status) register.
976.It Dv BHND_IOCTL_PME
977Enable posting of power management events by the core.
978.It Dv BHND_IOCTL_CLK_FORCE
979Force disable of clock gating, resulting in all clocks being distributed within
980the core.
981Should be set when asserting/deasserting reset to ensure the reset signal fully
982propagates to the entire core.
983.It Dv BHND_IOCTL_CLK_EN
984If cleared, the core clock will be disabled.
985Should be set during normal operation, and cleared when the core is held in
986reset.
987.It Dv BHND_IOCTL_CFLAGS
988The mask of IOCTL bits reserved for additional core-specific I/O control flags.
989.El
990.Pp
991The
992.Fn bhnd_read_iost
993function is used to read the I/O status register of device
994.Fa dev ,
995returning the current value in
996.Fa iost .
997The following I/O status flags are supported:
998.Bl -tag -width ".Dv BHND_IOST_BIST_DONE" -offset indent
999.It Dv BHND_IOST_BIST_DONE
1000Set upon BIST completion.
1001Will be cleared when the
1002.Dv BHND_IOCTL_BIST
1003flag of the I/O control register is cleared using
1004.Fn bhnd_write_ioctl .
1005.It Dv BHND_IOST_BIST_FAIL
1006Set upon detection of a BIST error; the value is unspecified if BIST has not
1007completed and
1008.Dv BHND_IOST_BIST_DONE
1009is not also set.
1010.It Dv BHND_IOST_CLK
1011Set if the core has required that clocked be ungated, or cleared otherwise.
1012The value is undefined if a core does not support clock gating.
1013.It Dv BHND_IOST_DMA64
1014Set if this core supports 64-bit DMA.
1015.It Dv BHND_IOST_CFLAGS
1016The mask of IOST bits reserved for additional core-specific I/O status flags.
1017.El
1018.Pp
1019The
1020.Fn bhnd_read_config
1021function is used to read a data item of
1022.Fa width
1023bytes at
1024.Fa offset
1025from the backplane-specific agent/config space of the device
1026.Fa dev .
1027.Pp
1028The
1029.Fn bhnd_write_config
1030function is used to write a data item of
1031.Fa width
1032bytes with
1033.Fa value
1034at
1035.Fa offset
1036from the backplane-specific agent/config space of the device
1037.Fa dev .
1038The requested
1039.Fa width
1040must be one of 1, 2, or 4 bytes.
1041.Pp
1042The agent/config space accessible via
1043.Fn bhnd_read_config
1044and
1045.Fn bhnd_write_config
1046is backplane-specific, and these functions should only be used for functionality
1047that is not available via another
1048.Nm
1049function.
1050.Pp
1051The
1052.Fn bhnd_suspend_hw
1053function transitions the device
1054.Fa dev
1055to a low power
1056.Dq RESET
1057state, writing
1058.Fa ioctl
1059to the I/O control flags of
1060.Fa dev .
1061The hardware may be brought out of this state using
1062.Fn bhnd_reset_hw .
1063.Pp
1064The
1065.Fn bhnd_reset_hw
1066function first transitions the device
1067.Fa dev
1068to a low power RESET state, writing
1069.Fa ioctl_reset
1070to the I/O control flags
1071of
1072.Fa dev ,
1073and then brings the device out of RESET, writing
1074.Fa ioctl
1075to the device's I/O control flags.
1076.Pp
1077The
1078.Fn bhnd_is_hw_suspended
1079function returns
1080.Dv true
1081if the device
1082.Fa dev
1083is currently held in a RESET state, or is otherwise not clocked.
1084Otherwise, it returns
1085.Dv false .
1086.Pp
1087Any outstanding per-device PMU requests made using
1088.Fn bhnd_enable_clocks ,
1089.Fn bhnd_request_clock ,
1090or
1091.Fn bhnd_request_ext_rsrc
1092will be released automatically upon placing a device into a RESET state.
1093.Ss "Device Information Functions"
1094The
1095.Fn bhnd_get_attach_type
1096function returns the attachment type of the parent
1097.Xr bhnd 4
1098bus of device
1099.Fa dev .
1100.Pp
1101The following attachment types are supported:
1102.Bl -hang -width ".Dv BHND_ATTACH_ADAPTER" -offset indent
1103.It Dv BHND_ATTACH_ADAPTER
1104The bus is resident on a bridged adapter, such as a PCI Wi-Fi device.
1105.It Dv BHND_ATTACH_NATIVE
1106The bus is resident on the native host, such as the primary or secondary bus of
1107an embedded SoC.
1108.El
1109.Pp
1110The
1111.Fn bhnd_get_chipid
1112function returns chip information from the parent
1113.Xr bhnd 4
1114bus of device
1115.Fa dev .
1116The returned
1117.Vt bhnd_chipid
1118struct contains the following fields:
1119.Pp
1120.Bl -tag -width "enum_addr" -offset indent
1121.It Fa chip_id
1122The chip identifier.
1123.It Fa chip_rev
1124The chip's hardware revision.
1125.It Fa chip_pkg
1126The chip's semiconductor package identifier.
1127.Pp
1128Several different physical semiconductor package variants may exist for a given
1129chip, each of which may require driver workarounds for hardware errata,
1130unpopulated components, etc.
1131.It Fa chip_type
1132The interconnect architecture used by this chip.
1133.It Fa enum_addr
1134The backplane enumeration address.
1135On SSB devices, this will be the base address of the first SSB core.
1136On BCMA devices, this will be the address of the enumeration ROM (EROM) core.
1137.It Fa ncores
1138The number of cores on the chip backplane, or 0 if unknown.
1139.El
1140.Pp
1141The following constants are defined for known
1142.Fa chip_type
1143values:
1144.Bl -tag -width ".Dv BHND_CHIPTYPE_BCMA_ALT" -offset indent -compact
1145.It Dv BHND_CHIPTYPE_SIBA
1146SSB interconnect.
1147.It Dv BHND_CHIPTYPE_BCMA
1148BCMA interconnect.
1149.It Dv BHND_CHIPTYPE_BCMA_ALT
1150BCMA-compatible variant found in Broadcom Northstar ARM SoCs.
1151.It Dv BHND_CHIPTYPE_UBUS
1152UBUS interconnect.
1153This BCMA-derived interconnect is found in Broadcom BCM33xx DOCSIS SoCs, and
1154BCM63xx xDSL SoCs.
1155UBUS is not currently supported by
1156.Xr bhnd 4 .
1157.El
1158.Pp
1159Additional symbolic constants for known
1160.Fa chip_id ,
1161.Fa chip_pkg ,
1162and
1163.Fa chip_type
1164values are defined in
1165.In dev/bhnd/bhnd_ids.h .
1166.Pp
1167The
1168.Fn bhnd_get_class
1169function returns the BHND class of device
1170.Fa dev ,
1171if the device's
1172.Em vendor
1173and
1174.Em device
1175identifiers are recognized.
1176Otherwise, returns
1177.Dv BHND_DEVCLASS_OTHER .
1178.Pp
1179One of the following device classes will be returned:
1180.Pp
1181.Bl -tag -width ".Dv BHND_DEVCLASS_SOC_ROUTER"  -offset indent -compact
1182.It Dv BHND_DEVCLASS_CC
1183ChipCommon I/O Controller
1184.It Dv BHND_DEVCLASS_CC_B
1185ChipCommon Auxiliary Controller
1186.It Dv BHND_DEVCLASS_PMU
1187PMU Controller
1188.It Dv BHND_DEVCLASS_PCI
1189PCI Host/Device Bridge
1190.It Dv BHND_DEVCLASS_PCIE
1191PCIe Host/Device Bridge
1192.It Dv BHND_DEVCLASS_PCCARD
1193PCMCIA Host/Device Bridge
1194.It Dv BHND_DEVCLASS_RAM
1195Internal RAM/SRAM
1196.It Dv BHND_DEVCLASS_MEMC
1197Memory Controller
1198.It Dv BHND_DEVCLASS_ENET
1199IEEE 802.3 MAC/PHY
1200.It Dv BHND_DEVCLASS_ENET_MAC
1201IEEE 802.3 MAC
1202.It Dv BHND_DEVCLASS_ENET_PHY
1203IEEE 802.3 PHY
1204.It Dv BHND_DEVCLASS_WLAN
1205IEEE 802.11 MAC/PHY/Radio
1206.It Dv BHND_DEVCLASS_WLAN_MAC
1207IEEE 802.11 MAC
1208.It Dv BHND_DEVCLASS_WLAN_PHY
1209IEEE 802.11 PHY
1210.It Dv BHND_DEVCLASS_CPU
1211CPU Core
1212.It Dv BHND_DEVCLASS_SOC_ROUTER
1213Interconnect Router
1214.It Dv BHND_DEVCLASS_SOC_BRIDGE
1215Interconnect Host Bridge
1216.It Dv BHND_DEVCLASS_EROM
1217Device Enumeration ROM
1218.It Dv BHND_DEVCLASS_NVRAM
1219NVRAM/Flash Controller
1220.It Dv BHND_DEVCLASS_SOFTMODEM
1221Analog/PSTN SoftModem Codec
1222.It Dv BHND_DEVCLASS_USB_HOST
1223USB Host Controller
1224.It Dv BHND_DEVCLASS_USB_DEV
1225USB Device Controller
1226.It Dv BHND_DEVCLASS_USB_DUAL
1227USB Host/Device Controller
1228.It Dv BHND_DEVCLASS_OTHER
1229Other / Unknown
1230.It Dv BHND_DEVCLASS_INVALID
1231Invalid Class
1232.El
1233.Pp
1234The
1235.Fn bhnd_get_core_info
1236function returns the core information for device
1237.Fa dev .
1238The returned
1239.Vt bhnd_core_info
1240structure contains the following fields:
1241.Pp
1242.Bl -tag -width "core_idx" -offset indent -compact
1243.It Fa vendor
1244Vendor identifier (JEP-106, ARM 4-bit continuation encoded)
1245.It Fa device
1246Device identifier
1247.It Fa hwrev
1248Hardware revision
1249.It Fa core_idx
1250Core index
1251.It Fa unit
1252Core unit
1253.El
1254.Pp
1255Symbolic constants for common vendor and device identifiers are defined in
1256.In dev/bhnd/bhnd_ids.h .
1257Common vendor identifiers include:
1258.Pp
1259.Bl -tag -width ".Dv BHND_MFGID_MIPS" -offset indent -compact
1260.It Dv BHND_MFGID_ARM
1261ARM
1262.It Dv BHND_MFGID_BCM
1263Broadcom
1264.It Dv BHND_MFGID_MIPS
1265MIPS
1266.El
1267.Pp
1268The
1269.Fn bhnd_get_core_index ,
1270.Fn bhnd_get_core_unit ,
1271.Fn bhnd_get_device ,
1272.Fn bhnd_get_hwrev ,
1273and
1274.Fn bhnd_get_vendor
1275functions are convenience wrappers for
1276.Fn bhnd_get_core_info ,
1277returning, respect the
1278.Fa core_idx ,
1279.Fa core_unit ,
1280.Fa device ,
1281.Fa hwrev ,
1282or
1283.Fa vendor
1284field from the
1285.Vt bhnd_core_info
1286structure.
1287.Pp
1288The
1289.Fn bhnd_get_device_name
1290function returns a human readable name for device
1291.Fa dev .
1292.Pp
1293The
1294.Fn bhnd_get_vendor_name
1295function returns a human readable name for the vendor of device
1296.Fa dev .
1297.Pp
1298The
1299.Fn bhnd_read_board_info
1300function attempts to read the board information for device
1301.Fa dev .
1302The board information will be returned in the location pointed to by
1303.Fa info
1304on success.
1305.Pp
1306The
1307.Vt bhnd_board_info
1308structure contains the following fields:
1309.Pp
1310.Bl -tag -width "board_srom_rev" -offset indent
1311.It Fa board_vendor
1312Vendor ID of the board manufacturer (PCI-SIG assigned).
1313.It Fa board_type
1314Board ID.
1315.It Fa board_devid
1316Device ID.
1317.It Fa board_rev
1318Board revision.
1319.It Fa board_srom_rev
1320Board SROM format revision.
1321.It Fa board_flags
1322Board flags (1)
1323.It Fa board_flags2
1324Board flags (2)
1325.It Fa board_flags3
1326Board flags (3)
1327.El
1328.Pp
1329The
1330.Fa board_devid
1331field is the Broadcom PCI device ID that most closely matches the
1332capabilities of the BHND device (if any).
1333.Pp
1334On PCI devices, the
1335.Fa board_vendor ,
1336.Fa board_type ,
1337and
1338.Fa board_devid
1339fields default to the PCI Subsystem Vendor ID, PCI Subsystem ID, and PCI
1340device ID, unless overridden in device NVRAM.
1341.Pp
1342On other devices, including SoCs, the
1343.Fa board_vendor ,
1344.Fa board_type ,
1345and
1346.Fa board_devid
1347fields will be populated from device NVRAM.
1348.Pp
1349Symbolic constants for common board flags are defined in
1350.In dev/bhnd/bhnd_ids.h .
1351.Pp
1352.Ss "Device Matching Functions"
1353The bhnd device matching functions are used to match against core, chip, and
1354board-level device attributes.
1355Match requirements are specified using the
1356.Vt "struct bhnd_board_match" ,
1357.Vt "struct bhnd_chip_match" ,
1358.Vt "struct bhnd_core_match" ,
1359.Vt "struct bhnd_device_match" ,
1360and
1361.Vt "struct bhnd_hwrev_match"
1362match descriptor structures.
1363.Pp
1364The
1365.Fn bhnd_board_matches
1366function returns
1367.Dv true
1368if
1369.Fa board
1370matches the board match descriptor
1371.Fa desc .
1372Otherwise, it returns
1373.Dv false .
1374.Pp
1375The
1376.Fn bhnd_chip_matches
1377function returns
1378.Dv true
1379if
1380.Fa chip
1381matches the chip match descriptor
1382.Fa desc .
1383Otherwise, it returns
1384.Dv false .
1385.Pp
1386The
1387.Fn bhnd_core_matches
1388function returns
1389.Dv true
1390if
1391.Fa core
1392matches the core match descriptor
1393.Fa desc .
1394Otherwise, it returns
1395.Dv false .
1396.Pp
1397The
1398.Fn bhnd_device_matches
1399function returns
1400.Dv true
1401if the device
1402.Fa dev
1403matches the device match descriptor
1404.Fa desc .
1405Otherwise, it returns
1406.Dv false .
1407.Pp
1408The
1409.Fn bhnd_hwrev_matches
1410function returns
1411.Dv true
1412if
1413.Fa hwrev
1414matches the hwrev match descriptor
1415.Fa desc .
1416Otherwise, it returns
1417.Dv false .
1418.Pp
1419The
1420.Fn bhnd_bus_match_child
1421function returns the first child device of
1422.Fa bus
1423that matches the device match descriptor
1424.Fa desc .
1425If no matching child is found,
1426.Dv NULL
1427is returned.
1428.Pp
1429The
1430.Fn bhnd_core_get_match_desc
1431function returns an equality match descriptor for the core info in
1432.Fa core .
1433The returned descriptor will match only on core attributes identical to those
1434defined by
1435.Fa core .
1436.Pp
1437The
1438.Fn bhnd_cores_equal
1439function is a convenience wrapper for
1440.Fn bhnd_core_matches
1441and
1442.Fn bhnd_core_get_match_desc .
1443This function returns
1444.Dv true
1445if the
1446.Vt bhnd_core_info
1447structures
1448.Fa lhs
1449and
1450.Fa rhs
1451are equal.
1452Otherwise, it returns
1453.Dv false .
1454.Pp
1455The
1456.Fn bhnd_match_core
1457function returns a pointer to the first entry in the array
1458.Fa cores
1459of length
1460.Fa num_cores
1461that matches
1462.Fa desc .
1463If no matching core is found,
1464.Dv NULL
1465is returned.
1466.Pp
1467A
1468.Vt bhnd_board_match
1469match descriptor may be initialized using one or more of the following macros:
1470.Pp
1471.Bl -tag -width "Fn BHND_MATCH_BOARD_VENDOR vendor" -offset indent
1472.It Fn BHND_MATCH_BOARD_VENDOR "vendor"
1473Match on boards with a vendor equal to
1474.Fa vendor .
1475.It Fn BHND_MATCH_BOARD_TYPE "type"
1476Match on boards with a type equal to
1477.Dv "BHND_BOARD_ ##"
1478.Fa type
1479.It Fn BHND_MATCH_SROMREV "sromrev"
1480Match on boards with a sromrev that matches
1481.Dv "BHND_HWREV_ ##"
1482.Fa sromrev .
1483.It Fn BHND_MATCH_BOARD_REV "hwrev"
1484Match on boards with hardware revisions that match
1485.Dv "BHND_ ##"
1486.Fa hwrev .
1487.It Fn BHND_MATCH_BOARD "vendor" "type"
1488A convenience wrapper for
1489.Fn BHND_MATCH_BOARD_VENDOR
1490and
1491.Fn BHND_MATCH_BOARD_TYPE .
1492.El
1493.Pp
1494For example:
1495.Bd -literal -offset indent
1496struct bhnd_board_match board_desc = {
1497	BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM),
1498	BHND_MATCH_BOARD_TYPE(BCM94360X52C),
1499	BHND_MATCH_BOARD_REV(HWREV_ANY),
1500	BHND_MATCH_SROMREV(RANGE(0, 10))
1501};
1502.Ed
1503.Pp
1504A
1505.Vt bhnd_chip_match
1506match descriptor may be initialized using one or more of the following macros:
1507.Pp
1508.Bl -tag -width "Fn BHND_MATCH_CHIP_IPR id pkg hwrev" -offset indent
1509.It Fn BHND_MATCH_CHIP_ID "id"
1510Match on chips with an ID equal to
1511.Dv "BHND_CHIPID_ ##"
1512.Fa id
1513.It Fn BHND_MATCH_CHIP_REV "hwrev"
1514Match on chips with hardware revisions that match
1515.Dv "BHND_ ##"
1516.Fa hwrev .
1517.It Fn BHND_MATCH_CHIP_PKG "pkg"
1518Match on chips with a package ID equal to
1519.Dv "BHND_PKGID_ ##"
1520.Fa pkg
1521.It Fn BHND_MATCH_CHIP_TYPE "type"
1522Match on chips with a chip type equal to
1523.Dv "BHND_CHIPTYPE_ ##"
1524.Fa type
1525.It Fn BHND_MATCH_CHIP_IP "id" "pkg"
1526A convenience wrapper for
1527.Fn BHND_MATCH_CHIP_ID
1528and
1529.Fn BHND_MATCH_CHIP_PKG .
1530.It Fn BHND_MATCH_CHIP_IPR "id" "pkg" "hwrev"
1531A convenience wrapper for
1532.Fn BHND_MATCH_CHIP_ID ,
1533.Fn BHND_MATCH_CHIP_PKG ,
1534and
1535.Fn BHND_MATCH_CHIP_REV .
1536.It Fn BHND_MATCH_CHIP_IR "id" "hwrev"
1537A convenience wrapper for
1538.Fn BHND_MATCH_CHIP_ID
1539and
1540.Fn BHND_MATCH_CHIP_REV .
1541.El
1542.Pp
1543For example:
1544.Bd -literal -offset indent
1545struct bhnd_chip_match chip_desc = {
1546	BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN),
1547	BHND_MATCH_CHIP_TYPE(SIBA)
1548};
1549.Ed
1550.Pp
1551A
1552.Vt bhnd_core_match
1553match descriptor may be initialized using one or more of the following macros:
1554.Pp
1555.Bl -tag -width "Fn BHND_MATCH_CORE_VENDOR vendor" -offset indent
1556.It Fn BHND_MATCH_CORE_VENDOR "vendor"
1557Match on cores with a vendor ID equal to
1558.Fa vendor
1559.It Fn BHND_MATCH_CORE_ID "id"
1560Match on cores with a device ID equal to
1561.Fa id
1562.It Fn BHND_MATCH_CORE_REV "hwrev"
1563Match on cores with hardware revisions that match
1564.Dv "BHND_ ##"
1565.Fa hwrev .
1566.It Fn BHND_MATCH_CORE_CLASS "class"
1567Match on cores with a core device class equal to
1568.Fa class
1569.It Fn BHND_MATCH_CORE_IDX "idx"
1570Match on cores with a core index equal to
1571.Fa idx
1572.It Fn BHND_MATCH_CORE_UNIT "unit"
1573Match on cores with a core unit equal to
1574.Fa unit
1575.It Fn BHND_MATCH_CORE "vendor" "id"
1576A convenience wrapper for
1577.Fn BHND_MATCH_CORE_VENDOR
1578and
1579.Fn BHND_MATCH_CORE_ID .
1580.El
1581.Pp
1582For example:
1583.Bd -literal -offset indent
1584struct bhnd_core_match core_desc = {
1585	BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC),
1586	BHND_MATCH_CORE_REV(HWREV_RANGE(0, 10))
1587};
1588.Ed
1589.Pp
1590The
1591.Vt bhnd_device_match
1592match descriptor supports matching on all board, chip, and core attributes,
1593and may be initialized using any of the
1594.Vt bhnd_board_match ,
1595.Vt bhnd_chip_match ,
1596or
1597.Vt bhnd_core_match
1598macros.
1599.Pp
1600For example:
1601.Bd -literal -offset indent
1602struct bhnd_device_match device_desc = {
1603	BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN),
1604	BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM),
1605	BHND_MATCH_BOARD_TYPE(BCM94329AGB),
1606	BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC),
1607};
1608.Ed
1609.Pp
1610A
1611.Vt bhnd_hwrev_match
1612match descriptor may be initialized using one of the following macros:
1613.Pp
1614.Bl -tag -width "Fn BHND_HWREV_RANGE start end" -offset indent -compact
1615.It Dv BHND_HWREV_ANY
1616Matches any hardware revision.
1617.It Fn BHND_HWREV_EQ "hwrev"
1618Matches any hardware revision equal to
1619.Fa hwrev
1620.It Fn BHND_HWREV_GTE "hwrev"
1621Matches any hardware revision greater than or equal to
1622.Fa hwrev
1623.It Fn BHND_HWREV_LTE "hwrev"
1624Matches any hardware revision less than or equal to
1625.Fa hwrev
1626.It Fn BHND_HWREV_RANGE "start" "end"
1627Matches any hardware revision within an inclusive range.
1628If
1629.Dv BHND_HWREV_INVALID
1630is specified as the
1631.Fa end
1632value, will match on any revision equal to or greater than
1633.Fa start
1634.El
1635.\"
1636.Ss "Device Table Functions"
1637The bhnd device table functions are used to query device and
1638quirk tables.
1639.Pp
1640The
1641.Fn bhnd_device_lookup
1642function returns a pointer to the first entry in device table
1643.Fa table
1644that matches the device
1645.Fa dev .
1646The table entry size is specified by
1647.Fa entry_size .
1648.Pp
1649The
1650.Fn bhnd_device_quirks
1651function scan the device table
1652.Fa table
1653for all quirk entries that match the device
1654.Fa dev ,
1655returning the bitwise OR of all matching quirk flags.
1656The table entry size is specified by
1657.Fa entry_size .
1658.Pp
1659The
1660.Vt bhnd_device
1661structure contains the following fields:
1662.Bl -tag -width "quirks_table" -offset indent -compact
1663.It Fa core
1664A
1665.Vt bhnd_device_match
1666descriptor.
1667.It Fa desc
1668A verbose device description suitable for use with
1669.Xr device_set_desc 9 ,
1670or
1671.Dv NULL .
1672.It Fa quirks_table
1673The quirks table for this device, or
1674.Dv NULL .
1675.It Fa device_flags
1676The device flags required when matching this entry.
1677.El
1678.Pp
1679The following device flags are supported:
1680.Bl -tag -width ".Dv BHND_DF_ADAPTER" -offset indent -compact
1681.It Dv BHND_DF_ANY
1682Match on any device.
1683.It Dv BHND_DF_HOSTB
1684Match only if the device is the
1685.Xr bhndb 4
1686host bridge.
1687Implies
1688.Dv BHND_DF_ADAPTER .
1689.It Dv BHND_DF_SOC
1690Match only if the device is attached to a native SoC backplane.
1691.It Dv BHND_DF_ADAPTER
1692Match only if the device is attached to a
1693.Xr bhndb 4
1694bridged backplane.
1695.El
1696.Pp
1697A
1698.Vt bhnd_device
1699table entry may be initialized using one of the following macros:
1700.Pp
1701.Bl -ohang -offset indent
1702.It Fn BHND_DEVICE "vendor" "device" "desc" "quirks" "flags"
1703Match on devices with a vendor ID equal to
1704.Dv BHND_MFGID_ ##
1705.Fa vendor
1706and a core device ID equal to
1707.Dv BHND_COREID_ ##
1708.Fa device .
1709.Pp
1710The device's verbose description is specified by the
1711.Fa desc
1712argument, a pointer to the device-specific quirks table is specified by the
1713.Fa quirks
1714argument, and any required device flags may be provided in
1715.Fa flags .
1716The optional
1717.Fa flags
1718argument defaults to
1719.Dv BHND_DF_ANY
1720if omitted.
1721.It Dv BHND_DEVICE_END
1722Terminate the
1723.Vt bhnd_device
1724table.
1725.El
1726.Pp
1727For example:
1728.Bd -literal -offset indent
1729struct bhnd_device bhnd_usb11_devices[] = {
1730	BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller",
1731	    bhnd_usb11_quirks),
1732	BHND_DEVICE_END
1733};
1734.Ed
1735.Pp
1736The
1737.Vt bhnd_device_quirk
1738structure contains the following fields:
1739.Bl -tag -width "quirks_table" -offset indent -compact
1740.It Fa desc
1741A
1742.Vt bhnd_device_match
1743descriptor.
1744.It Fa quirks
1745Applicable quirk flags.
1746.El
1747.Pp
1748A bhnd_device_quirk table entry may be initialized using one of the following
1749convenience macros:
1750.Bl -tag -width "Fn BHND_CHIP_QUIRK chip hwrev flags" -offset indent
1751.It Fn BHND_BOARD_QUIRK "board" "flags"
1752Set quirk flags
1753.Fa flags
1754on devices with a board type equal to
1755.Dv BHND_BOARD_ ##
1756.Fa board .
1757.It Fn BHND_CHIP_QUIRK "chip" "hwrev" "flags"
1758Set quirk flags
1759.Fa flags
1760on devices with a chip ID equal to
1761.Dv BHND_CHIPID_BCM ##
1762.Fa chip
1763and chip hardware revision that matches
1764.Dv BHND_ ##
1765.Fa hwrev .
1766.It Fn BHND_PKG_QUIRK "chip" "pkg" flags"
1767Set quirk flags
1768.Fa flags
1769on devices with a chip ID equal to
1770.Dv BHND_CHIPID_BCM ##
1771.Fa chip
1772and chip package equal to
1773.Dv BHND_ ## chip ##
1774.Fa pkg .
1775.It Fn BHND_CORE_QUIRK "hwrev" flags"
1776Set quirk flags
1777.Fa flags
1778on devices with a core hardware revision that matches
1779.Dv BHND_ ##
1780.Fa hwrev .
1781.El
1782For example:
1783.Bd -literal -offset indent
1784struct bhnd_device_quirk bhnd_usb11_quirks[] = {
1785	BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller",
1786	    bhnd_usb11_quirks),
1787	BHND_DEVICE_END
1788};
1789.Ed
1790.Ss "DMA Address Translation Functions"
1791The
1792.Fn bhnd_get_dma_translation
1793function is used to request a DMA address translation descriptor suitable
1794for use with a maximum DMA address width of
1795.Fa width ,
1796with support for the requested translation
1797.Fa flags .
1798.Pp
1799If a suitable DMA address translation descriptor is found, it will be stored in
1800.Fa translation ,
1801and a bus DMA tag specifying the DMA translation's address restrictions will
1802be stored in
1803.Fa dmat .
1804The
1805.Fa translation
1806and
1807.Fa dmat
1808arguments may be
1809.Dv NULL
1810if the translation descriptor or DMA tag are not desired.
1811.Pp
1812The following DMA translation flags are supported:
1813.Bl -ohang -width ".Dv BHND_DMA_TRANSLATION_BYTESWAPPED" -offset indent
1814.It Dv BHND_DMA_TRANSLATION_PHYSMAP
1815The translation remaps the device's physical address space.
1816.Pp
1817This is used in conjunction with
1818.Dv BHND_DMA_TRANSLATION_BYTESWAPPED
1819to define a DMA translation that provides byteswapped access to physical memory
1820on big-endian MIPS SoCs.
1821.It Dv BHND_DMA_TRANSLATION_BYTESWAPPED
1822The translation provides a byte-swapped mapping; write requests will be
1823byte-swapped before being written to memory, and read requests will be
1824byte-swapped before being returned.
1825.Pp
1826This is primarily used to perform efficient byte swapping of DMA data on
1827embedded MIPS SoCs executing in big-endian mode.
1828.El
1829.Pp
1830The following symbolic constants are defined for common DMA address widths:
1831.Pp
1832.Bl -tag -width ".Dv BHND_DMA_ADDR_64BIT" -offset indent -compact
1833.It Dv BHND_DMA_ADDR_30BIT
183430-bit DMA
1835.It Dv BHND_DMA_ADDR_32BIT
183632-bit DMA
1837.It Dv BHND_DMA_ADDR_64BIT
183864-bit DMA
1839.El
1840.Pp
1841The
1842.Vt bhnd_dma_translation
1843structure contains the following fields:
1844.Bl -tag -width "addrext_mask"
1845.It Fa base_addr
1846Host-to-device physical address translation.
1847This may be added to a host physical address to produce a device DMA address.
1848.It Fa addr_mask
1849Device-addressable address mask.
1850This defines the device DMA address range, and excludes any bits reserved for
1851mapping the address within the translation window at
1852.Fa base_addr .
1853.It Fa addrext_mask
1854Device-addressable extended address mask.
1855If a the per-core BHND DMA engine supports the 'addrext' control field, it can
1856be used to provide address bits excluded by
1857.Fa addr_mask .
1858.Pp
1859Support for DMA extended address changes \(em including coordination with the
1860core providing device-to-host DMA address translation \(em is handled
1861transparently by the DMA engine.
1862.Pp
1863For example, on PCI Wi-Fi devices, the Wi-Fi core's DMA engine will (in effect)
1864update the PCI host bridge core's DMA
1865.Dv sbtopcitranslation
1866base address to map the target address prior to performing a DMA transaction.
1867.It Fa flags
1868Translation flags.
1869.El
1870.\"
1871.Ss "Interrupt Functions"
1872The
1873.Fn bhnd_get_intr_count
1874function is used to determine the number of backplane interrupt lines assigned
1875to the device
1876.Fa dev .
1877Interrupt line identifiers are allocated in monotonically increasing order,
1878starting with 0.
1879.Pp
1880The
1881.Fn bhnd_get_intr_ivec
1882function is used to determine the backplane interrupt vector assigned to
1883interrupt line
1884.Fa intr
1885on the device
1886.Fa dev ,
1887writing the result to
1888.Fa ivec .
1889Interrupt vector assignments are backplane-specific: On BCMA devices, this
1890function returns the OOB bus line assigned to the interrupt.
1891On SIBA devices, it returns the target OCP slave flag number assigned to the
1892interrupt.
1893.Pp
1894The
1895.Fn bhnd_map_intr
1896function is used to map interrupt line
1897.Fa intr
1898assigned to device
1899.Fa dev
1900to an IRQ number, writing the result to
1901.Fa irq .
1902Until unmapped, this IRQ may be used when allocating a resource of type
1903SYS_RES_IRQ.
1904.Pp
1905Ownership of the interrupt mapping is assumed by the caller, and must be
1906explicitly released using
1907.Fa bhnd_unmap_intr .
1908.Pp
1909The
1910.Fn bhnd_unmap_intr
1911function is used to unmap bus IRQ
1912.Fa irq
1913previously mapped using
1914.Fn bhnd_map_intr
1915by the device
1916.Fa dev .
1917.\"
1918.Ss "NVRAM Functions"
1919The
1920.Fn bhnd_nvram_getvar
1921function is used to read the value of NVRAM variable
1922.Fa name
1923from the NVRAM provider(s) registered with the parent
1924.Xr bhnd 4
1925bus of device
1926.Fa dev ,
1927coerced to the desired data representation
1928.Fa type ,
1929written to the buffer specified by
1930.Fa buf .
1931.Pp
1932Before the call, the maximum capacity of
1933.Fa buf
1934is specified by
1935.Fa len .
1936After a successful call \(em or if
1937.Er ENOMEM
1938is returned \(em the size of the available data will be written to
1939.Fa len .
1940The size of the desired data representation can be determined by calling
1941.Fn bhnd_nvram_getvar
1942with a
1943.Dv NULL
1944argument for
1945.Fa buf .
1946.Pp
1947The following NVRAM data types are supported:
1948.Pp
1949.Bl -tag -width ".Dv BHND_NVRAM_TYPE_UINT64_ARRAY" -offset indent -compact
1950.It Dv BHND_NVRAM_TYPE_UINT8
1951unsigned 8-bit integer
1952.It Dv BHND_NVRAM_TYPE_UINT16
1953unsigned 16-bit integer
1954.It Dv BHND_NVRAM_TYPE_UINT32
1955unsigned 32-bit integer
1956.It Dv BHND_NVRAM_TYPE_UINT64
1957signed 64-bit integer
1958.It Dv BHND_NVRAM_TYPE_INT8
1959signed 8-bit integer
1960.It Dv BHND_NVRAM_TYPE_INT16
1961signed 16-bit integer
1962.It Dv BHND_NVRAM_TYPE_INT32
1963signed 32-bit integer
1964.It Dv BHND_NVRAM_TYPE_INT64
1965signed 64-bit integer
1966.It Dv BHND_NVRAM_TYPE_CHAR
1967UTF-8 character
1968.It Dv BHND_NVRAM_TYPE_STRING
1969UTF-8 NUL-terminated string
1970.It Dv BHND_NVRAM_TYPE_BOOL
1971uint8 boolean value
1972.It Dv BHND_NVRAM_TYPE_NULL
1973NULL (empty) value
1974.It Dv BHND_NVRAM_TYPE_DATA
1975opaque octet string
1976.It Dv BHND_NVRAM_TYPE_UINT8_ARRAY
1977array of uint8 integers
1978.It Dv BHND_NVRAM_TYPE_UINT16_ARRAY
1979array of uint16 integers
1980.It Dv BHND_NVRAM_TYPE_UINT32_ARRAY
1981array of uint32 integers
1982.It Dv BHND_NVRAM_TYPE_UINT64_ARRAY
1983array of uint64 integers
1984.It Dv BHND_NVRAM_TYPE_INT8_ARRAY
1985array of int8 integers
1986.It Dv BHND_NVRAM_TYPE_INT16_ARRAY
1987array of int16 integers
1988.It Dv BHND_NVRAM_TYPE_INT32_ARRAY
1989array of int32 integers
1990.It Dv BHND_NVRAM_TYPE_INT64_ARRAY
1991array of int64 integers
1992.It Dv BHND_NVRAM_TYPE_CHAR_ARRAY
1993array of UTF-8 characters
1994.It Dv BHND_NVRAM_TYPE_STRING_ARRAY
1995array of UTF-8 NUL-terminated strings
1996.It Dv BHND_NVRAM_TYPE_BOOL_ARRAY
1997array of uint8 boolean values
1998.El
1999.Pp
2000The
2001.Fn bhnd_nvram_getvar_array ,
2002.Fn bhnd_nvram_getvar_int ,
2003.Fn bhnd_nvram_getvar_int8 ,
2004.Fn bhnd_nvram_getvar_int16 ,
2005.Fn bhnd_nvram_getvar_int32 ,
2006.Fn bhnd_nvram_getvar_uint ,
2007.Fn bhnd_nvram_getvar_uint8 ,
2008.Fn bhnd_nvram_getvar_uint16 ,
2009.Fn bhnd_nvram_getvar_uint32 ,
2010and
2011.Fn bhnd_nvram_getvar_str
2012functions are convenience wrappers for
2013.Fn bhnd_nvram_getvar .
2014.Pp
2015The
2016.Fn bhnd_nvram_getvar_array
2017function returns either a value of exactly
2018.Fa size
2019in
2020.Fa buf ,
2021or returns an error code of
2022.Er ENXIO
2023if the data representation is not exactly
2024.Fa size
2025in length.
2026.Pp
2027The
2028.Fn bhnd_nvram_getvar_int
2029and
2030.Fn bhnd_nvram_getvar_uint
2031functions return the value of NVRAM variable
2032.Fa name ,
2033coerced to a signed or unsigned integer
2034type of
2035.Fa width
2036(1, 2, or 4 bytes).
2037.Pp
2038The
2039.Fn bhnd_nvram_getvar_int8 ,
2040.Fn bhnd_nvram_getvar_int16 ,
2041.Fn bhnd_nvram_getvar_int32 ,
2042.Fn bhnd_nvram_getvar_uint ,
2043.Fn bhnd_nvram_getvar_uint8 ,
2044.Fn bhnd_nvram_getvar_uint16 ,
2045and
2046.Fn bhnd_nvram_getvar_uint32
2047functions return the value of NVRAM variable
2048.Fa name ,
2049coerced to a signed or unsigned 8, 16, or 32-bit integer type.
2050.Pp
2051The
2052.Fn bhnd_nvram_getvar_str
2053functions return the value of NVRAM variable
2054.Fa name ,
2055coerced to a NUL-terminated string.
2056.Pp
2057The
2058.Fn bhnd_nvram_string_array_next
2059function iterates over all strings in the
2060.Fa inp
2061.Dv BHND_NVRAM_TYPE_STRING_ARRAY
2062value.
2063The size of
2064.Fa inp ,
2065including any terminating NUL character(s), is specified using the
2066.Fa ilen
2067argument.
2068The
2069.Fa prev
2070argument should be either a string pointer previously returned by
2071.Fn bhnd_nvram_string_array_next ,
2072or
2073.Dv NULL
2074to begin iteration.
2075If
2076.Fa prev is not
2077.Dv NULL ,
2078the
2079.Fa olen
2080argument must be a pointer to the length previously returned by
2081.Fn bhnd_nvram_string_array_next .
2082On success, the next string element's length will be written to this pointer.
2083.\"
2084.Ss "Port/Region Functions"
2085Per-device interconnect memory mappings are identified by a combination of
2086.Em port type ,
2087.Em port number ,
2088and
2089.Em region number .
2090Port and memory region identifiers are allocated in monotonically increasing
2091order for each
2092.Em port type ,
2093starting with 0.
2094.Pp
2095The following port types are supported:
2096.Bl -tag -width ".Dv BHND_PORT_DEVICE" -offset indent
2097.It Dv BHND_PORT_DEVICE
2098Device memory.
2099The device's control/status registers are always mapped by the first device port
2100and region, and will be assigned a
2101.Dv SYS_RES_MEMORY
2102resource ID of 0.
2103.It Dv BHND_PORT_BRIDGE
2104Bridge memory.
2105.It Dv BHND_PORT_AGENT
2106Interconnect agent/wrapper.
2107.El
2108.Pp
2109The
2110.Fn bhnd_decode_port_rid
2111function is used to decode the resource ID
2112.Fa rid
2113assigned to device
2114.Fa dev ,
2115of resource type
2116.Fa type ,
2117writing the port type to
2118.Fa port_type ,
2119port number to
2120.Fa port ,
2121and region number
2122to
2123.Fa region .
2124.Pp
2125The
2126.Fn bhnd_get_port_count
2127function returns the number of ports of type
2128.Fa type
2129assigned to device
2130.Fa dev .
2131.Pp
2132The
2133.Fn bhnd_get_port_rid
2134function returns the resource ID for the
2135.Dv SYS_RES_MEMORY
2136resource mapping the
2137.Fa port
2138of
2139.Fa type
2140and
2141.Fa region
2142on device
2143.Fa dev ,
2144or -1 if the port or region are invalid, or do not have an assigned resource ID.
2145.Pp
2146The
2147.Fn bhnd_get_region_addr
2148function is used to determine the base address and size of the memory
2149.Fa region
2150on
2151.Fa port
2152of
2153.Fa type
2154assigned to
2155.Fa dev .
2156The region's base device address will be written to
2157.Fa region_addr ,
2158and the region size to
2159.Fa region_size .
2160.Pp
2161The
2162.Fn bhnd_get_region_count
2163function returns the number of memory regions mapped to
2164.Fa port
2165of
2166.Fa type
2167on device
2168.Fa dev .
2169.Pp
2170The
2171.Fn bhnd_is_region_valid
2172function returns
2173.Dv true
2174if
2175.Fa region
2176is a valid region mapped by
2177.Fa port
2178of
2179.Fa type
2180on device
2181.Fa dev .
2182.\"
2183.Ss "Power Management Functions"
2184Drivers must ask the parent
2185.Xr bhnd 4
2186bus to allocate device PMU state using
2187.Fn bhnd_alloc_pmu
2188before calling any another bhnd PMU functions.
2189.Pp
2190The
2191.Fn bhnd_alloc_pmu
2192function is used to allocate per-device PMU state and enable PMU request
2193handling for device
2194.Fa dev .
2195The memory region containing the device's PMU register block must be allocated
2196using
2197.Xr bus_alloc_resource 9
2198or
2199.Fn bhnd_alloc_resource
2200before calling
2201.Fn bhnd_alloc_pmu ,
2202and must not be released until after calling
2203.Fn bhnd_release_pmu .
2204.Pp
2205On all supported BHND hardware, the PMU register block is mapped by the device's
2206control/status registers in the first device port and region.
2207.Pp
2208The
2209.Fn bhnd_release_pmu
2210function releases the per-device PMU state previously allocated for device
2211.Fa dev
2212using
2213.Fn bhnd_alloc_pmu .
2214Any outstanding clock and external resource requests will be discarded upon
2215release of the device PMU state.
2216.Pp
2217The
2218.Fn bhnd_enable_clocks
2219function is used to request that
2220.Fa clocks
2221be powered up and routed to the backplane on behalf of device
2222.Fa dev .
2223This will power any clock sources required (e.g., XTAL, PLL, etc) and wait until
2224the requested clocks are stable.
2225If the request succeeds, any previous clock requests issued by
2226.Fa dev
2227will be discarded.
2228.Pp
2229The following clocks are supported, and may be combined using bitwise OR to
2230request multiple clocks:
2231.Pp
2232.Bl -tag -width ".Dv BHND_CLOCK_DYN" -offset indent
2233.It BHND_CLOCK_DYN
2234Dynamically select an appropriate clock source based on all outstanding clock
2235requests by any device attached to the parent
2236.Xr bhnd 4
2237bus.
2238.It BHND_CLOCK_ILP
2239Idle Low-Power (ILP) Clock.
2240May be used if no register access is required, or long request latency is
2241acceptable.
2242.It BHND_CLOCK_ALP
2243Active Low-Power (ALP) Clock.
2244Supports low-latency register access and low-rate DMA.
2245.It BHND_CLOCK_HT
2246High Throughput (HT) Clock.
2247Supports high bus throughput and lowest-latency register access.
2248.El
2249.Pp
2250The
2251.Fn bhnd_request_clock
2252function is used to request that
2253.Fa clock
2254(or faster) be powered up and routed to device
2255.Fa dev .
2256.Pp
2257The
2258.Fn bhnd_get_clock_freq
2259function is used to request the current clock frequency of
2260.Fa clock ,
2261writing the frequency in Hz to
2262.Fa freq .
2263.Pp
2264The
2265.Fn bhnd_get_clock_latency
2266function is used to determine the transition latency required for
2267.Fa clock ,
2268writing the latency in microseconds to
2269.Fa latency .
2270The
2271.Dv BHND_CLOCK_HT
2272latency value is suitable for use as the D11 Wi-Fi core
2273.Em fastpwrup_dly
2274value.
2275.Pp
2276The
2277.Fn bhnd_request_ext_rsrc
2278function is used to request that the external PMU-managed resource assigned to
2279device
2280.Fa dev ,
2281identified by device-specific identifier
2282.Fa rsrc ,
2283be powered up.
2284.Pp
2285The
2286.Fn bhnd_release_ext_rsrc
2287function releases any outstanding requests by device
2288.Fa dev
2289for the PMU-managed resource identified by device-specific identifier
2290.Fa rsrc .
2291If an external resource is shared by multiple devices, it will not be powered
2292down until all device requests are released.
2293.\"
2294.Ss "Service Provider Functions"
2295The
2296.Fn bhnd_register_provider
2297function is used to register device
2298.Fa dev
2299as a provider for platform
2300.Fa service
2301with the parent
2302.Xr bhnd 4
2303bus.
2304.Pp
2305The following service types are supported:
2306.Bl -tag -width ".Dv BHND_SERVICE_INVALID" -offset indent
2307.It Dv BHND_SERVICE_CHIPC
2308ChipCommon service.
2309The providing device must implement the bhnd_chipc interface.
2310.It Dv BHND_SERVICE_PWRCTL
2311Legacy PWRCTL service.
2312The providing device must implement the bhnd_pwrctl interface.
2313.It Dv BHND_SERVICE_PMU
2314PMU service.
2315The providing device must implement the bhnd_pmu interface.
2316.It Dv BHND_SERVICE_NVRAM
2317NVRAM service.
2318The providing device must implement the bhnd_nvram interface.
2319.It Dv BHND_SERVICE_GPIO
2320GPIO service.
2321The providing device must implement the standard
2322.Xr gpio 4
2323interface.
2324.It Dv BHND_SERVICE_ANY
2325Matches on any service type.
2326May be used with
2327.Fn bhnd_deregister_provider
2328to remove all service provider registrations for a device.
2329.El
2330.Pp
2331The
2332.Fn bhnd_deregister_provider
2333function attempts to remove provider registration for the device
2334.Fa dev
2335and
2336.Fa service .
2337If a
2338.Fa service
2339argument of
2340.Dv BHND_SERVICE_ANY
2341is specified, this function will attempt to remove
2342.Em all service provider registrations for
2343.Fa dev .
2344.Pp
2345The
2346.Fn bhnd_retain_provider
2347function retains and returns a reference to the provider registered for
2348.Fa service
2349with the parent
2350.Xr bhnd 4
2351bus of devce
2352.Fa dev ,
2353if available.
2354On success, the caller is responsible for releasing this provider reference
2355using
2356.Fn bhnd_release_provider .
2357The service provider is guaranteed to remain available until the provider
2358reference is released.
2359.Pp
2360The
2361.Fn bhnd_release_provider
2362function releases a reference to a
2363.Fa provider
2364for
2365.Fa service ,
2366previously retained by device
2367.Fa dev
2368using
2369.Fn bhnd_retain_provider .
2370.\"
2371.Ss "Utility Functions"
2372The
2373.Fn bhnd_driver_get_erom_class
2374function returns the
2375.Xr bhnd_erom 9
2376class for the device enumeration table format used by
2377.Xr bhnd 4
2378bus driver instance
2379.Fa driver .
2380If the driver does not support
2381.Xr bhnd_erom 9
2382device enumeration,
2383.Dv NULL
2384is returned.
2385.Pp
2386The
2387.Fn bhnd_find_core_class
2388function looks up the BHND class, if known, for the BHND vendor ID
2389.Fa vendor
2390and device ID
2391.Fa device .
2392.Pp
2393The
2394.Fn bhnd_find_core_name
2395function is used to fetch the human-readable name, if known, for the BHND core
2396with a vendor ID of
2397.Fa vendor
2398and device ID of
2399.Fa device .
2400.Pp
2401The
2402.Fn bhnd_core_class
2403and
2404.Fn bhnd_core_name
2405functions are convenience wrappers for
2406.Fn bhnd_find_core_class
2407and
2408.Fn bhnd_find_core_name ,
2409that use the
2410.Fa vendor
2411and
2412.Fa device
2413fields of the core info structure
2414.Fa ci .
2415.Pp
2416The
2417.Fn bhnd_format_chip_id
2418function writes a NUL-terminated human-readable representation of the BHND
2419.Fa chip_id
2420value to the specified
2421.Fa buffer
2422with a capacity of
2423.Fa size .
2424No more than
2425.Fa size-1
2426characters will be written, with the
2427.Fa size'th
2428character set to '\\0'.
2429A buffer size of
2430.Dv BHND_CHIPID_MAX_NAMELEN
2431is sufficient for any string representation produced using
2432.Fn bhnd_format_chip_id .
2433.Pp
2434The
2435.Fn bhnd_set_custom_core_desc
2436function uses the
2437.Xr bhnd 4
2438device identification of
2439.Fa dev ,
2440overriding the core name with the specified
2441.Fa dev_name ,
2442to populate the device's verbose description using
2443.Xr device_set_desc .
2444.Pp
2445The
2446.Fn bhnd_set_default_core_desc
2447function uses the
2448.Xr bhnd 4
2449device identification of
2450.Fa dev
2451to populate the device's verbose description using
2452.Xr device_set_desc .
2453.Pp
2454The
2455.Fn bhnd_vendor_name
2456function returns the human-readable name for the JEP-106, ARM 4-bit
2457continuation encoded manufacturer ID
2458.Fa vendor ,
2459if known.
2460.\"
2461.Sh RETURN VALUES
2462.Ss Bus Resource Functions
2463The
2464.Fn bhnd_activate_resource ,
2465.Fn bhnd_alloc_resources ,
2466.Fn bhnd_deactivate_resource ,
2467and
2468.Fn bhnd_release_resource
2469functions return 0 on success, otherwise an appropriate error code is returned.
2470.Pp
2471The
2472.Fn bhnd_alloc_resource
2473and
2474.Fn bhnd_alloc_resource_any
2475functions return a pointer to
2476.Vt "struct resource"
2477on success, a null pointer otherwise.
2478.\"
2479.Ss "Device Configuration Functions"
2480.Pp
2481The
2482.Fn bhnd_read_config
2483and
2484.Fn bhnd_write_config
2485functions return 0 on success, or one of the following values on error:
2486.Bl -tag -width Er
2487.It Bq Er EINVAL
2488The device is not a direct child of the
2489.Xr bhnd 4
2490bus
2491.It Bq Er EINVAL
2492The requested width is not one of 1, 2, or 4 bytes.
2493.It Bq Er ENODEV
2494Accessing agent/config space for the device is unsupported.
2495.It Bq Er EFAULT
2496The requested offset or width exceeds the bounds of the mapped agent/config
2497space.
2498.El
2499.Pp
2500The
2501.Fn bhnd_read_ioctl ,
2502.Fn bhnd_write_ioctl ,
2503.Fn bhnd_read_iost ,
2504.Fn bhnd_reset_hw ,
2505and
2506.Fn bhnd_suspend_hw
2507functions return 0 on success, otherwise an appropriate error code is returned.
2508.\"
2509.Ss "Device Information Functions"
2510.Pp
2511The
2512.Fn bhnd_read_board_info
2513function returns 0 on success, otherwise an appropriate error code is returned.
2514.\"
2515.Ss "DMA Address Translation Functions"
2516The
2517.Fn bhnd_get_dma_translation
2518function returns 0 on success, or one of the following values on error:
2519.Bl -tag -width Er
2520.It Bq Er ENODEV
2521DMA is not supported.
2522.It Bq Er ENOENT
2523No DMA translation matching the requested address width and translation flags
2524is available.
2525.El
2526.Pp
2527If fetching the requested DMA address translation otherwise fails, an
2528appropriate error code will be returned.
2529.\"
2530.Ss "Interrupt Functions"
2531.Pp
2532The
2533.Fn bhnd_get_intr_ivec
2534function returns
25350 on success, or
2536.Er ENXIO
2537if the requested interrupt line exceeds the number of interrupt lines assigned
2538to the device.
2539.Pp
2540The
2541.Fn bhnd_map_intr
2542function returns 0 on success, otherwise an appropriate error code is returned.
2543.\"
2544.Ss "NVRAM Functions"
2545The
2546.Fn bhnd_nvram_getvar ,
2547.Fn bhnd_nvram_getvar_array ,
2548.Fn bhnd_nvram_getvar_int ,
2549.Fn bhnd_nvram_getvar_int8 ,
2550.Fn bhnd_nvram_getvar_int16 ,
2551.Fn bhnd_nvram_getvar_int32 ,
2552.Fn bhnd_nvram_getvar_uint ,
2553.Fn bhnd_nvram_getvar_uint8 ,
2554.Fn bhnd_nvram_getvar_uint16 ,
2555and
2556.Fn bhnd_nvram_getvar_uint32
2557functions return 0 on success, or one of the following values on error:
2558.Bl -tag -width Er
2559.It Bq Er ENODEV
2560If an NVRAM provider has not been registered with the bus.
2561.It Bq Er ENOENT
2562The requested variable was not found.
2563.It Bq Er ENOMEM
2564If the buffer of size is too small to hold the requested value.
2565.It Bq Er EOPNOTSUPP
2566If the value's native type is incompatible with and cannot be coerced to the
2567requested type.
2568.It Bq Er ERANGE
2569If value coercion would overflow (or underflow) the requested type
2570.El
2571.Pp
2572If reading the variable otherwise fails, an appropriate error code will be
2573returned.
2574.\"
2575.Ss "Port/Region Functions"
2576The
2577.Fn bhnd_decode_port_rid
2578function returns
25790 on success, or an appropriate error code if no matching port/region is found.
2580.Pp
2581The
2582.Fn bhnd_get_port_rid
2583function returns the resource ID for the requested port and region,
2584or -1 if the port or region are invalid, or do not have an assigned resource ID.
2585.Pp
2586The
2587.Fn bhnd_get_region_addr
2588function returns
25890 on success, or an appropriate error code if no matching port/region is found.
2590.\"
2591.Ss "PMU Functions"
2592The
2593.Fn bhnd_alloc_pmu
2594function returns 0 on success, otherwise an appropriate error code is returned.
2595.Pp
2596The
2597.Fn bhnd_release_pmu
2598function returns 0 on success, otherwise an appropriate error code is returned,
2599and the core state will be left unmodified.
2600.Pp
2601The
2602.Fn bhnd_enable_clocks
2603and
2604.Fn bhnd_request_clock
2605functions return 0 on success, or one of the following values on error:
2606.Bl -tag -width Er
2607.It Bq Er ENODEV
2608An unsupported clock was requested.
2609.It Bq Er ENXIO
2610No PMU or PWRCTL provider has been registered with the bus.
2611.El
2612.Pp
2613The
2614.Fn bhnd_get_clock_freq
2615function returns 0 on success, or
2616.Er ENODEV
2617if the frequency for the specified clock is not available.
2618.Pp
2619The
2620.Fn bhnd_get_clock_latency
2621function returns 0 on success, or
2622.Er ENODEV
2623if the transition latency for the specified clock is not available.
2624.Pp
2625The
2626.Fn bhnd_request_ext_rsrc
2627and
2628.Fn bhnd_release_ext_rsrc
2629functions return 0 on success, otherwise an appropriate error code is returned.
2630.Pp
2631.\"
2632.Ss "Service Provider Functions"
2633The
2634.Fn bhnd_register_provider
2635function returns 0 on success,
2636.Er EEXIST
2637if an entry for service already exists, or an appropriate error code if
2638service registration otherwise fails.
2639.Pp
2640The
2641.Fn bhnd_deregister_provider
2642function returns 0 on success, or
2643.Er EBUSY
2644if active references to the service provider exist.
2645.Pp
2646The
2647.Fn bhnd_retain_provider
2648function returns a pointer to
2649.Vt "device_t"
2650on success, a null pointer if the requested provider is not registered.
2651.\"
2652.Ss "Utility Functions"
2653.Pp
2654The
2655.Fn bhnd_format_chip_id
2656function returns the total number of bytes written on success, or a negative
2657integer on failure.
2658.\"
2659.Sh SEE ALSO
2660.Xr bhnd 4
2661.Xr bhnd_erom 9
2662.Sh AUTHORS
2663.An -nosplit
2664The
2665.Nm
2666driver programming interface and this manual page were written by
2667.An Landon Fuller Aq Mt landonf@FreeBSD.org .
2668