Repository navigation
Expand file tree
/
Copy pathnextbsd-e16-tickets.html
More file actions
1460 lines (1459 loc) · 344 KB
/
Copy pathnextbsd-e16-tickets.html
File metadata and controls
1460 lines (1459 loc) · 344 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>E16 ticket drafts — Bluetooth</title>
<style>
:root {
--bg: #fbfbf8;
--fg: #1a1a1a;
--muted: #555;
--accent: #b03000;
--accent2: #0a4d68;
--ok: #1f7a1f;
--warn: #b06800;
--bad: #b00020;
--code-bg: #f0ece4;
--rule: #d6cfc0;
--card: #fff;
}
html { -webkit-text-size-adjust: 100%; }
body { margin: 0 auto; max-width: 1080px; padding: 2.5rem 1.5rem 6rem;
font: 16px/1.55 -apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif;
color: var(--fg); background: var(--bg); }
h1 { font-size: 2rem; line-height: 1.2; margin: 0 0 .25rem; }
h2 { font-size: 1.4rem; margin: 2.5rem 0 .75rem; padding-bottom: .25rem; border-bottom: 2px solid var(--rule); }
h3 { font-size: 1.15rem; margin: 1.75rem 0 .5rem; color: var(--accent2); }
h4 { margin: 1.25rem 0 .35rem; }
.subtitle { color: var(--muted); font-size: 1.05rem; margin: 0 0 2rem; }
code, pre, kbd { font-family: "SF Mono", Menlo, Consolas, monospace; }
code { background: var(--code-bg); padding: 1px 5px; border-radius: 3px; font-size: .9em; }
pre { background: var(--code-bg); padding: .85rem 1rem; border-radius: 6px;
overflow-x: auto; font-size: .82rem; line-height: 1.45;
border-left: 3px solid var(--accent2); }
pre code { background: none; padding: 0; }
pre.shell { border-left-color: var(--ok); }
pre.c { border-left-color: var(--accent); }
a { color: var(--accent2); }
a:hover { color: var(--accent); }
.tldr { background: var(--card); border: 1px solid var(--rule); border-left: 4px solid var(--accent2);
padding: 1rem 1.25rem; border-radius: 6px; margin-bottom: 2rem; }
.tldr h3 { margin-top: 0; color: var(--accent2); }
.pill { display: inline-block; font-size: .72rem; padding: 1px 8px; border-radius: 999px;
background: #eee; color: #333; margin-left: .35rem; vertical-align: middle;
font-weight: 600; letter-spacing: .02em; }
.pill.ok { background: #d8efd8; color: var(--ok); }
.pill.warn { background: #f6e4cb; color: var(--warn); }
.pill.bad { background: #f5d0d6; color: var(--bad); }
.pill.info { background: #d6e6f3; color: var(--accent2); }
table { border-collapse: collapse; width: 100%; margin: 1rem 0; font-size: .92rem; }
th, td { text-align: left; padding: .5rem .65rem; border-bottom: 1px solid var(--rule); vertical-align: top; }
th { background: #eee5d6; }
tr:nth-child(even) td { background: #faf6ed; }
table.compact td, table.compact th { padding: .35rem .55rem; font-size: .88rem; }
.nav { position: sticky; top: 0; background: var(--bg); margin: -2.5rem -1.5rem 2rem;
padding: .75rem 1.5rem; border-bottom: 1px solid var(--rule);
font-size: .88rem; z-index: 10; }
.nav a { margin-right: .9rem; text-decoration: none; }
.gap { background: #fff5f5; border-left: 4px solid var(--bad); padding: .8rem 1rem; margin: 1rem 0; border-radius: 0 6px 6px 0; }
.gap strong { color: var(--bad); }
.resolved { background: #ecf7ec; border-left: 4px solid var(--ok); padding: .8rem 1rem; margin: 1rem 0; border-radius: 0 6px 6px 0; }
.resolved strong { color: var(--ok); }
.open-q { background: #fff8d6; border: 1px solid #e5d76b; padding: .8rem 1rem; margin: 1rem 0; border-radius: 6px; font-size: .92rem; }
.open-q strong { color: #7a5e00; }
.risk { background: #fff5f5; border: 1px solid #e7b8bf; border-left: 4px solid var(--bad); padding: .8rem 1rem; margin: 1rem 0; border-radius: 6px; font-size: .93rem; }
.risk strong { color: var(--bad); }
.ascii-diagram { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: .82rem; line-height: 1.3; white-space: pre; background: var(--code-bg); padding: 1rem; border-radius: 6px; overflow-x: auto; }
.rec { background: #eef4f8; border: 1px solid #bcd4e2; border-left: 4px solid var(--accent2); padding: 1rem 1.25rem; margin: 1.25rem 0; border-radius: 6px; }
.rec strong { color: var(--accent2); }
.yesno { font-weight: 600; }
.yesno.yes { color: var(--ok); }
.yesno.no { color: var(--bad); }
.yesno.partial { color: var(--warn); }
</style>
<style>
.tk { background: var(--card); border: 1px solid var(--rule); border-left: 4px solid var(--accent2); border-radius: 6px; padding: .9rem 1.1rem .4rem; margin: 1.25rem 0; }
.tk h3 { margin-top: .1rem; }
.tk .meta { font-size: .88rem; margin: .25rem 0 .6rem; border-collapse: collapse; }
.tk .meta td { padding: .15rem .8rem .15rem 0; vertical-align: top; }
.tk .meta td:first-child { color: var(--muted); white-space: nowrap; }
.tk pre { white-space: pre-wrap; word-wrap: break-word; }
.tk-epic { border-left-color: var(--accent); }
</style>
<style>@media (max-width:640px){ body{padding:1.5rem 1rem 4rem;} .nav{margin:-1.5rem -1rem 1.5rem;padding:.6rem 1rem;} table{display:block;overflow-x:auto;} }</style>
</head><body>
<nav class="nav"><a href="#tldr">TL;DR</a><a href="#merged">Merged drafts</a><a href="#tickets">Tickets</a><a href="nextbsd-bluetooth-plan.html">Plan</a></nav>
<p style="font-size:.9rem;margin:0 0 1rem"><a href="nextbsd-research.html">← NextBSD Research</a></p>
<h1>E16 ticket drafts — Bluetooth <span class="pill ok">All filed</span></h1>
<p class="subtitle"><strong>Every issue for EPIC E16 (<a href="https://github.com/nextbsd/nextbsd/issues/473">nextbsd#473</a>), written out in full:</strong> title, repo, labels, size, track, dependencies and the exact Markdown body. Companion to the <a href="nextbsd-bluetooth-plan.html">Bluetooth plan</a>. All 38 are filed as sub-issues of #473 on the <a href="https://github.com/orgs/nextbsd/projects/1/views/8">roadmap</a> (Epic = E16 Bluetooth), with native blocked-by links and a Dependencies footer on each.</p>
<section id="tldr" class="tldr"><h3>TL;DR</h3><ul>
<li><strong>38 tickets across 3 repos:</strong> nextbsd, nextbsd-kernel and nextbsd-userland. The new <code>area:bluetooth</code> label is in all three.</li>
<li><strong>Draft ids by area:</strong> K = kernel & hardware · B = engine / BLE · D = bluetoothd & CLI · H = HID · A = audio.</li>
<li><strong>Critical path:</strong> K1 → D1 → B2 → D2 → D5 → D4 → D8 → H2 (keyboards) / A4 (headphones).</li>
<li><strong>Machine-readable:</strong> every field is embedded as JSON (<code><script id="e16-data"></code>).</li></ul></section>
<h2 id="merged">Merged drafts</h2><ul>
<li><strong>H1</strong> (bake <code>vkbd</code>) and <strong>A1</strong> (bake <code>cuse</code>) → merged into <strong>K1</strong>, so there’s one kernel config change.</li>
<li><strong>B3</strong> (Classic engine) → merged into <strong>D4</strong>. Both replaced <code>hcsecd</code> and added SSP.</li>
<li><strong>B1</strong> (decision record) → recorded in <a href="https://github.com/nextbsd/nextbsd/issues/412">nextbsd#412</a> instead of a new ticket.</li></ul>
<h2 id="tickets">Tickets</h2>
<h3>Stage 0 — kernel & image</h3>
<section id="K1" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">K1 · config: bake netgraph + the Bluetooth stack, vkbd and cuse into NEXTBSD — no .ko tree, so nothing can autoload (#412 phase 0) <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-kernel</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>area:bluetooth</code> <code>area:kext</code> <code>enhancement</code></td></tr><tr><th>Depends on</th><td colspan="5">—</td></tr></table>
<h2>Problem</h2>
<p>NextBSD has no Bluetooth at all (nextbsd/nextbsd#412): <code>config/NEXTBSD</code> carries no <code>NETGRAPH*</code> option, and neither amd64 nor arm64 GENERIC does either (<code>grep -i netgraph sys/{amd64,arm64}/conf/GENERIC</code> is empty). On stock FreeBSD that is fine because <code>rc.d/bluetooth</code> kldloads <code>ng_bluetooth ng_hci ng_l2cap ng_btsocket</code> (<code>libexec/rc/rc.d/bluetooth:8</code>) and <code>ng_socket.c:281-303</code> <code>kern_kldload</code>s <code>ng_<type></code> on any <code>NGM_MKPEER</code> for an unknown type. NextBSD deletes the whole <code>.ko</code> tree at image assembly (<code>ci/assemble-image.sh:168</code>), so every one of those paths fails — the <code>wlan_xauth</code> trap (#51, #52) again. Plugging in a dongle today gives a <code>ugen</code> with nothing to claim it.</p>
<h2>Change</h2>
<p>Add to <code>config/NEXTBSD</code> (shared by amd64, arm64 and NEXTBSD-RPI5, which <code>include</code>s it), with a comment block in the file's house style explaining the no-<code>.ko</code>-tree reason:</p>
<pre><code>options NETGRAPH # netgraph core (ng_base, ng_parse)
options NETGRAPH_SOCKET # ng_socket: PF_NETGRAPH — ngctl/libnetgraph/hccontrol find nodes through it
options NETGRAPH_BLUETOOTH # ng_bluetooth: net.bluetooth sysctls; MODULE_DEPEND of every BT node
options NETGRAPH_BLUETOOTH_HCI # ng_hci
options NETGRAPH_BLUETOOTH_L2CAP # ng_l2cap
options NETGRAPH_BLUETOOTH_SOCKET # ng_btsocket: PF_BLUETOOTH (HCI raw / L2CAP / RFCOMM / SCO); DOMAIN_SET, never autoloadable
options NETGRAPH_BLUETOOTH_UBT # ng_ubt + ng_ubt_intel + ng_ubt_rtl: USB HCI transport (class E0/01/01, Broadcom/Apple vendor-class)
</code></pre>
<p>Every token is stock and machine-independent: <code>sys/conf/options:516-526</code>, <code>sys/conf/files:4299-4320</code> (<code>ng_ubt*.c</code> are <code>optional netgraph_bluetooth_ubt usb</code>), <code>sys/conf/NOTES:813-818</code>. All <code>MODULE_DEPEND</code>s resolve inside this set plus <code>usb</code>, which both GENERICs already bake (<code>sys/arm64/conf/std.dev:101</code>). No src-overlay, no patch.</p>
<p>Deliberately <strong>not</strong> added: <code>NETGRAPH_BLUETOOTH_UBTBCMFW</code> (2003-era BCM2033 firmware cdev whose firmware is unshippable, <code>usr.sbin/bluetooth/bcmfw/bcmfw.8:54-56</code>), and <code>NETGRAPH_BLUETOOTH_H4</code>/<code>_BT3C</code> (dead tokens — <code>ng_h4</code> was removed in 2021, commit 79a100e28e).</p>
<p>What this does <strong>not</strong> do: nothing in the kernel builds the HCI/L2CAP graph. <code>ng_ubt</code> attaches a bare <code>ubtN</code> node; assembling <code>ubtNhci</code>/<code>ubtNl2cap</code> and wiring the <code>btsock_*</code> nodes is what <code>rc.d/bluetooth</code> did behind devd's <code>bluetooth.conf</code>, and on NextBSD it becomes <code>bluetoothd</code>'s job (area 2). Until then it is done by hand with <code>ngctl</code> (K6).</p>
<h2>Acceptance</h2>
<ul>
<li>[ ] <code>config/NEXTBSD</code> carries the seven options above with a comment in the file's style (cite <code>assemble-image.sh:168</code>, <code>ng_socket.c:281-303</code>, #52)</li>
<li>[ ] <code>config -x</code> of the built kernel (amd64 and arm64 legs, and the NEXTBSD-RPI5 leg) lists all seven options</li>
<li>[ ] qemu boot test on both arches: <code>ngctl list</code> shows <code>btsock_hci_raw</code>, <code>btsock_l2c_raw</code>, <code>btsock_l2c</code>; <code>ngctl types</code> lists <code>hci</code>, <code>l2cap</code>, <code>ubt</code>, <code>socket</code>; <code>sysctl -n net.bluetooth.version</code> prints a number</li>
<li>[ ] <code>hccontrol read_bd_addr</code> exits 7 with <code>Could not find HCI nodes</code> (<code>usr.sbin/bluetooth/hccontrol/hccontrol.c:110-112</code>) — i.e. PF_BLUETOOTH and PF_NETGRAPH exist; it must <strong>not</strong> say <code>Could not create socket</code></li>
<li>[ ] The image ships <code>/usr/sbin/{hccontrol,ngctl,l2ping,sdpcontrol,sdpd,hcsecd,bthidd,iwmbtfw,rtlbtfw}</code> (expected from the compat <code>buildworld</code> with <code>MK_BLUETOOTH</code> default yes, <code>share/mk/src.opts.mk:70</code>; verify, since the srclist plan once marked <code>ngctl</code> DEFER)</li>
<li>[ ] Kernel size delta recorded in the PR (<code>size</code> on <code>kernel</code> before/after; estimate is ~0.4–0.5 MB, unmeasured)</li>
<li>[ ] The wired <code>em0</code>/virtio DHCP path in the boot test is unchanged (purely additive change)</li>
<li>[ ] <code>ng_socket.c:281-303</code> is added to the #52 audit table as "covered by baking the BT types"</li>
</ul>
<h2>Related</h2>
<ul>
<li>nextbsd/nextbsd#473 (E16), nextbsd/nextbsd#412 (seed, phase 0)</li>
<li>
<h1>51, #52 (the lazy-kldload trap), #54 (the wlan_xauth fix, the precedent for this PR)</h1>
</li>
<li>K2 (CI assertions), K6 (hand verification)</li>
</ul>
<hr />
<h2>Also in this change: vkbd (Bluetooth HID keyboards)</h2>
<p><em>Merged from E16 draft H1.</em></p>
<h2>Why</h2>
<p><code>bthidd(8)</code> opens <code>/dev/vkbdctl</code> <strong>unconditionally</strong> for every device whose HID descriptor has a keyboard page, and fails the session if it cannot (<code>usr.sbin/bluetooth/bthidd/session.c:106-115</code>, releng/15.1). This is independent of <code>-u</code>/uinput. <code>vkbd(4)</code> is a module on stock FreeBSD (<code>sys/conf/files:3501 optional vkbd</code>; not in <code>sys/amd64/conf/GENERIC</code> nor <code>sys/arm64/conf/std.dev</code>), and the stock <code>rc.d/bthidd</code> <code>load_kld</code>s it (<code>libexec/rc/rc.d/bthidd:34-38</code>). NextBSD ships no <code>.ko</code> tree (<code>ci/assemble-image.sh:168</code>), so on today's <code>config/NEXTBSD</code> (which only <code>include</code>s GENERIC, line 1) no Bluetooth keyboard can ever attach, and the only symptom is a syslog line. Same class of bug as <code>wlan_xauth</code> (#51) and <code>hms</code>/<code>hmt</code> (#335), documented at <code>config/NEXTBSD:153-159</code>.</p>
<p>The rest of the bthidd sink path is already in GENERIC and inherited: <code>options EVDEV_SUPPORT</code>, <code>device evdev</code>, <code>device uinput</code> (<code>GENERIC:381-383</code>, <code>std.dev:72-74</code>) and <code>device kbdmux</code> (<code>GENERIC:199</code>, <code>std.dev:49</code>). <code>kbd_register()</code> auto-attaches every new keyboard, including each vkbd, to kbdmux (<code>sys/dev/kbd/kbd.c:197-231</code>). That inheritance is inferred, not yet observed on a shipped kernel; this ticket makes it verified.</p>
<h2>Change</h2>
<p>In <code>config/NEXTBSD</code>, next to the HID block, add:</p>
<pre><code># Bluetooth HID (E16). bthidd(8) feeds every BT keyboard into a vkbd(4)
# instance (session.c:106-115), which kbd_register() auto-attaches to kbdmux.
# vkbd is module-only upstream (sys/conf/files: optional vkbd) and rc.d/bthidd
# kldloads it -- impossible here (no .ko tree), so it must be static.
# evdev/uinput/kbdmux come from GENERIC and are the other half of the path.
device vkbd
</code></pre>
<p>No overlay needed: <code>vkbd</code> is a stock config token. Valid on amd64 and arm64 (MI, <code>sys/conf/files</code>).</p>
<h2>Acceptance</h2>
<ul>
<li>[ ] <code>config/NEXTBSD</code> contains <code>device vkbd</code> with the comment above; both matrix legs build green.</li>
<li>[ ] On the built kernel: <code>config -x /boot/kernel/kernel | grep -E '^(device|options)[[:space:]]+(vkbd|uinput|evdev|kbdmux|EVDEV_SUPPORT)$'</code> prints all five.</li>
<li>[ ] On a booted image: <code>/dev/vkbdctl</code>, <code>/dev/uinput</code>, <code>/dev/kbdmux0</code>, <code>/dev/consolectl</code> exist; <code>sysctl kern.evdev.rcpt_mask</code> exists.</li>
<li>[ ] A synthetic vkbd keyboard (open <code>/dev/vkbdctl</code>, write scancodes) produces keystrokes on the console (<code>dmesg</code>/tty) — this is the manual precursor of H8.</li>
</ul>
<h2>Links</h2>
<ul>
<li>Epic nextbsd/nextbsd#473, seed nextbsd/nextbsd#412</li>
<li><code>usr.sbin/bluetooth/bthidd/session.c</code>, <code>sys/dev/vkbd/vkbd.c:674</code>, <code>sys/dev/kbd/kbd.c:197-231</code></li>
<li>Netgraph/Bluetooth nodes themselves are area K's ticket; this one is needed regardless of which nodes are baked.</li>
</ul>
<hr />
<h2>Also in this change: cuse (virtual_oss / Bluetooth audio)</h2>
<p><em>Merged from E16 draft A1.</em></p>
<h2>Why</h2>
<p>Bluetooth audio on FreeBSD 15 is <code>virtual_oss(8)</code>, which is now in base (<code>usr.sbin/virtual_oss</code>, <code>lib/libcuse</code>) and exposes its mixed device through <strong>cuse(3)</strong> — a userland character-device framework. The <code>cuse</code> kernel module is <code>optional</code> in <code>sys/conf/files:3603</code> (<code>fs/cuse/cuse.c optional cuse</code>), is <strong>not</strong> in amd64 <code>GENERIC</code> or arm64 <code>std.dev</code>, and on stock FreeBSD is <code>kldload</code>ed on demand (the port's rc script has <code>required_modules="cuse"</code>). NextBSD deletes the whole <code>.ko</code> tree at image assembly (<code>ci/assemble-image.sh:168</code>), so this is the <code>wlan_xauth</code> / <code>snd_uaudio</code> / <code>snd_hda</code> unbaked-leaf trap again: <code>virtual_oss</code> starts, finds no <code>/dev/cuse</code>, and exits. Same dependency for <code>webcamd</code> and the DriverKit-shape userland-driver plan (<code>cuse</code> is catalogued as <code>org.nextbsd.kpi.CUSE</code> in the kld-to-kext catalog), so the line pays for itself beyond Bluetooth.</p>
<h2>Exact change</h2>
<p>In <code>config/NEXTBSD</code>, next to the <code>snd_uaudio</code> / <code>snd_hda</code> block (lines ~188-240), add with the usual rationale comment:</p>
<pre><code># Userland character devices (cuse(3)). virtual_oss(8) -- FreeBSD 15's base
# audio mixer and the Bluetooth A2DP path -- creates its /dev/dsp* nodes
# through cuse. Module-only on stock FreeBSD (sys/conf/files: optional cuse),
# and NextBSD ships no .ko tree, so it must be static. MI, no MODULE_DEPENDs.
device cuse
</code></pre>
<p>It reaches <code>NEXTBSD-RPI5</code> through its <code>include NEXTBSD</code>.</p>
<h2>Acceptance criteria</h2>
<ul>
<li>[ ] <code>device cuse</code> present in <code>config/NEXTBSD</code>; amd64 and arm64 kernels build clean in CI</li>
<li>[ ] On the qemu boot test, <code>ls -l /dev/cuse</code> exists after boot (add to <code>tests/boot-test.sh</code> alongside the <code>/dev/sndstat</code> check)</li>
<li>[ ] <code>virtual_oss -f /dev/dsp0 -d dsp.test -t dsp.test.ctl</code> on the boot-test VM gets past <code>cuse_init()</code> (it will still die at <code>kldload("cuse.ko")</code> until A3 lands — record that in the test as expected-fail until then)</li>
</ul>
<h2>Links</h2>
<ul>
<li>Epic nextbsd/nextbsd#473, seed nextbsd/nextbsd#412</li>
<li>Sibling trap: nextbsd/nextbsd-kernel#51 (<code>wlan_xauth</code>), and the <code>snd_uaudio</code>/<code>snd_hda</code> comments in <code>config/NEXTBSD:188-240</code></li>
<li><code>sys/conf/files:3603</code>, <code>sys/fs/cuse/cuse.c</code>, <code>lib/libcuse/cuse.3</code> (releng/15.1)</li>
<li>Research: <code>e16/5-audio.md</code> section 1</li>
</ul></section>
<section id="K2" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">K2 · boot-test: assert the Bluetooth stack is present on both arches (ngctl list/types, net.bluetooth, hccontrol exits 7) and guard the kernel options <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd/issues/475">nextbsd#475</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code> <code>area:ci</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>)</td></tr></table>
<h2>Problem</h2>
<p>The failure mode K1 fixes is silent: drop one <code>NETGRAPH_*</code> option and the kernel still boots; the symptom is <code>hccontrol: Could not create socket: Address family not supported by protocol family</code> or <code>ngctl: send msg: No such file or directory</code> months later on someone's laptop. #52 asked for exactly this kind of guard. There is no Bluetooth in qemu (the emulation was removed in 2019, qemu commits 1d4ffe8dc7 and 43d68d0a94), so CI cannot prove a radio works — but it can prove the stack is there and that the userland tools reach it.</p>
<h2>Change</h2>
<p>Extend the qemu boot harness (<code>tests/boot-test.sh</code> / <code>tests/img-boot-test.sh</code>, both arches) with a Bluetooth block that runs after login and fails the job on any miss:</p>
<pre><code class="language-sh">ngctl list | grep -q '^ *Name: btsock_hci_raw ' # ng_btsocket nodes exist at boot (ng_btsocket_hci_raw.c:197-207)
ngctl list | grep -q 'btsock_l2c_raw'
ngctl list | grep -q 'btsock_l2c '
ngctl types | grep -Eq '^ *Type name: (hci|l2cap|ubt|socket) ' # one line each; adjust to ngctl's exact format
sysctl -n net.bluetooth.version # ENOENT before K1
hccontrol read_bd_addr; test $? -eq 7 # "Could not find HCI nodes" — PF_BLUETOOTH + PF_NETGRAPH work
l2ping -a 00:00:00:00:00:01 2>&1 | grep -qv 'socket' # fails on connect, not on socket(2)
for b in hccontrol ngctl l2ping sdpcontrol sdpd hcsecd bthidd iwmbtfw rtlbtfw; do test -x /usr/sbin/$b; done
</code></pre>
<p>and, in the kernel repo's build job (or here, on the downloaded kernel), a <code>config -x</code> check that all seven options from K1 are present — the same idea as the existing <code>KEXTD-LOAD</code> / linuxulator probes.</p>
<p>Keep the strings exact and cite the source line each one comes from, so a future upstream change in <code>hccontrol</code>'s wording fails loudly rather than passing vacuously.</p>
<h2>Acceptance</h2>
<ul>
<li>[ ] Both arch legs run the block and pass on a K1 kernel</li>
<li>[ ] Reverting K1 locally makes the block fail on the first <code>ngctl list</code> line (negative test done once, recorded in the PR)</li>
<li>[ ] The <code>config -x</code> option guard is wired (kernel repo build job or image assembly — whichever the maintainers prefer; say which)</li>
<li>[ ] No new runtime cost beyond a few commands at the end of the existing boot transcript</li>
</ul>
<h2>Related</h2>
<ul>
<li>K1 (the options), K5 (the emulator that will make this block exercise real HCI traffic later)</li>
<li>nextbsd/nextbsd-kernel#52</li>
</ul></section>
<section id="K3" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">K3 · Ship Intel (ibt-*) and Realtek (rtl_bt) Bluetooth firmware in the image, with licences — fetched at assembly like the Pi DTBs <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd/issues/476">nextbsd#476</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>)</td></tr></table>
<h2>Problem</h2>
<p>Intel Wireless-AC/AX combo cards (VID 0x8087: 7260/7265, 8260/8265, 9260/9560, AX200-class — the twelve PIDs in <code>sys/netgraph/bluetooth/drivers/ubt/ng_ubt_intel.c:89-105</code>) and Realtek 87xx/88xx parts enumerate in bootloader/ROM mode. The in-tree drivers deliberately refuse to attach until operational firmware is loaded (<code>ng_ubt_intel.c:33-37</code>: attaching in bootloader mode "locks the adapter hardly so it requires power on/off cycle"; <code>ng_ubt_rtl.c:172-181</code>). The loaders are in base — <code>iwmbtfw(8)</code>, <code>rtlbtfw(8)</code> — but they read the firmware from a directory (<code>-f</code>), and NextBSD ships none: <code>/boot/firmware</code> is deleted at assembly (<code>nextbsd-kernel/ci/assemble-image.sh:169</code>, and #392 removes a stray <code>iwm*</code>), and the kext firmware-bundle path (patch 0004, <code>firmware(9)</code>) does not apply because these blobs are consumed by userland tools, not the kernel. Every Intel laptop we already target for WLAN (IntelWiFi.kext) has one of these Bluetooth halves.</p>
<h2>Change</h2>
<p>Do what <code>build.sh:444-482</code> already does for the Pi DTBs and <code>LICENCE.broadcom</code>: fetch at image assembly, pinned, with the licence beside the blobs.</p>
<ul>
<li>Source: the same Debian <code>non-free-firmware</code> <code>.deb</code>s the FreeBSD ports use (<code>comms/iwmbt-firmware</code>: <code>firmware-iwlwifi_<ver>_all.deb</code>, extract <code>usr/lib/firmware/intel/ibt-*</code> + <code>usr/share/doc/firmware-iwlwifi/copyright</code>; <code>comms/rtlbt-firmware</code>: <code>firmware-realtek_<ver>_all.deb</code>, extract <code>usr/lib/firmware/rtl_bt/*</code> + its <code>copyright</code>). Pin the Debian version the way <code>RPI_FIRMWARE_TAG</code> is pinned. Licences are Intel's and Realtek's firmware licences; the ports declare <code>LICENSE_PERMS= dist-mirror dist-sell pkg-mirror pkg-sell auto-accept</code>, i.e. redistribution is allowed with the notice.</li>
<li>Install to <code>/usr/share/firmware/bluetooth/intel/</code> and <code>/usr/share/firmware/bluetooth/rtl_bt/</code>, with <code>COPYRIGHT.intel</code> / <code>COPYRIGHT.realtek</code> alongside. (A data-only <code>org.nextbsd.firmware.bluetooth</code> bundle under <code>/System/Library/Extensions</code> was considered; OSKext authentication and kextd gain nothing from an executable-less bundle, so a plain directory wins. Say so in the comment.)</li>
<li>Measure the Intel set; if it is tens of MB, trim to the <code>ibt-<hw_variant>-<hw_revision>*</code> families that <code>iwmbtfw</code>'s selection logic can actually pick for the twelve PIDs, and record the mapping.</li>
<li>Consumers: <code>iwmbtfw -d ugenX.Y -f /usr/share/firmware/bluetooth/intel</code>, <code>rtlbtfw -d ugenX.Y -f /usr/share/firmware/bluetooth/rtl_bt</code> — run by <code>bluetoothd</code> per K4.</li>
</ul>
<p>Out of scope: Broadcom <code>.hcd</code> patchram for USB parts (ROM firmware works; no loader in base), Atheros <code>ath3k</code> (no port, rare), the Pi 5 <code>BCM4345C0.hcd</code> (K8).</p>
<h2>Acceptance</h2>
<ul>
<li>[ ] <code>build.sh</code> fetches both <code>.deb</code>s at a pinned version, verifies a checksum, and stages the two directories plus licence files; the fetch is cached in <code>$DIST</code> like the DTBs</li>
<li>[ ] The image contains <code>/usr/share/firmware/bluetooth/{intel,rtl_bt}</code> and both licence files; the size of each is recorded in the PR</li>
<li>[ ] <code>iwmbtfw -f /usr/share/firmware/bluetooth/intel -d <ugen></code> on a real Intel part (K6 hardware) results in the device re-enumerating and <code>ubt0</code> attaching — recorded in the hardware matrix</li>
<li>[ ] Nothing lands under <code>/boot/firmware</code> (#392 stays fixed)</li>
<li>[ ] README/PORTING note the licence and the pinning</li>
</ul>
<h2>Related</h2>
<ul>
<li>nextbsd/nextbsd#392, #473, #412</li>
<li>K4 (who runs the loaders), K6 (hardware proof)</li>
<li>FreeBSD ports <code>comms/iwmbt-firmware</code>, <code>comms/rtlbt-firmware</code></li>
</ul></section>
<section id="A2" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">A2 · Ship virtual_oss's Bluetooth backend (`/usr/local/lib/virtual_oss/voss_bt.so`) on the image <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd/issues/485">nextbsd#485</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>)</td></tr></table>
<h2>Why</h2>
<p>FreeBSD 15 base ships <code>virtual_oss(8)</code> but <strong>builds only the <code>null</code> and <code>oss</code> backends</strong> (<code>lib/virtual_oss/Makefile</code>: <code>SUBDIR+= null oss</code>). The Bluetooth backend sources are in the tree (<code>lib/virtual_oss/bt/</code>: <code>bt.c</code>, <code>avdtp.c</code>, <code>sbc_encode.c</code>, <code>SHLIB_NAME= voss_bt.so</code>, <code>LIBADD= bluetooth sdp</code>) but are packaged by the ports tree as <code>audio/virtual_oss_bluetooth</code> (<code>WRKSRC=${SRC_BASE}/lib/virtual_oss/bt</code>, <code>PLIST_FILES= lib/virtual_oss/voss_bt.so</code>). <code>virtual_oss</code> dlopens it from a <strong>hard-coded</strong> <code>/usr/local/lib/virtual_oss/voss_bt.so</code> whenever a device string starts with <code>/dev/bluetooth/</code> (<code>usr.sbin/virtual_oss/virtual_oss/main.c:1650, 1671-1672, 1686-1687</code>) and <code>errx(1)</code>s if it is missing. Without this file there is no A2DP on NextBSD at all.</p>
<p>SBC is built in; AAC is a compile option (<code>HAVE_LIBAV</code>) that drags in <code>multimedia/gstreamer1-libav</code>. Ship SBC-only.</p>
<h2>Exact change</h2>
<p>Preferred, zero code: add <code>virtual_oss_bluetooth</code> to <code>pkglist.txt</code> so <code>build.sh</code> step 5b installs it from the FreeBSD:15 repo into the rootfs (it already lays down <code>/usr/local</code> packages that way). <strong>First verify the binary package exists</strong> (<code>pkg -r $RF -o REPOS_DIR=$FBSD_REPOS search virtual_oss_bluetooth</code>): the port is <code>DISTVERSION=${OSVERSION}</code> and <code>IGNORE</code>s without <code>/usr/src</code>, so it is plausible the cluster skips it.</p>
<p>Fallback if the package is absent: build <code>lib/virtual_oss/bt</code> in the base build (nextbsd-freebsd-compat: append <code>SUBDIR.${MK_BLUETOOTH}+= bt</code> to <code>lib/virtual_oss/Makefile</code> via a patch, and either install to <code>/usr/local/lib/virtual_oss/</code> or patch <code>main.c:1672/1687</code> to use prefix <code>/usr</code>), or as a tiny target in nextbsd-userland that compiles the three files from the FreeBSD source snapshot. Record which path was taken in <code>PORTING.md</code>.</p>
<h2>Acceptance criteria</h2>
<ul>
<li>[ ] <code>/usr/local/lib/virtual_oss/voss_bt.so</code> present in both <code>.img</code> and <code>.iso</code> rootfs; <code>ldd</code> resolves <code>libbluetooth.so</code> and <code>libsdp.so</code></li>
<li>[ ] <code>nm -D</code> exports <code>voss_backend_bt_play</code> and <code>voss_backend_bt_rec</code></li>
<li>[ ] On the boot-test VM (no radio), <code>virtual_oss -R /dev/null -P /dev/bluetooth/00:00:00:00:00:00 -d dsp.bt -t dsp.bt.ctl</code> gets past <code>dlopen</code> and fails at the SDP/L2CAP step with a clear message (proves loading, not connectivity)</li>
<li>[ ] Decision on package vs. base build recorded in <code>PORTING.md</code></li>
</ul>
<h2>Links</h2>
<ul>
<li>Epic nextbsd/nextbsd#473 · A1 (cuse) · A3 (kldload trap)</li>
<li><code>audio/virtual_oss_bluetooth/Makefile</code> and <code>pkg-descr</code> (freebsd-ports main); <code>lib/virtual_oss/bt/Makefile</code> (releng/15.1)</li>
<li>Research: <code>e16/5-audio.md</code> section 1.2</li>
</ul></section>
<section id="A3" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">A3 · kldload(2) of a statically linked module returns ENOENT on NextBSD — virtual_oss dies at `kldload("cuse.ko")` even with cuse baked <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-kernel/issues/236">nextbsd-kernel#236</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-kernel</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>bug</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>)</td></tr></table>
<h2>Why</h2>
<p><code>virtual_oss</code> self-heals on stock FreeBSD with</p>
<pre><code class="language-c">/* usr.sbin/virtual_oss/virtual_oss/main.c:2554 */
if (kldload("cuse.ko") < 0 && errno != EEXIST)
err(1, "Failed to load cuse kernel module");
</code></pre>
<p>It expects <code>EEXIST</code> when cuse is already in the kernel. That is <strong>not</strong> what the linker returns on NextBSD. <code>sys/kern/kern_linker.c:1218-1224</code> treats any name containing <code>.</code> as a <em>file name</em> (<code>kldname = file; modname = NULL</code>); <code>linker_load_module()</code> (:2264-2282) then only does <code>linker_search_kld(kldname)</code> and returns <strong><code>ENOENT</code></strong> when no file exists — the <code>modlist_lookup2()</code> -> <code>EEXIST</code> branch is reached only for bare module names. Because NextBSD removes every <code>.ko</code> (<code>ci/assemble-image.sh:168</code>), a baked <code>cuse</code> still yields <code>ENOENT</code>, and <code>virtual_oss</code> exits before creating any device. <code>webcamd</code> and other cuse consumers carry the identical call. This is the userland face of the <code>wlan_xauth</code> class (#51): the kernel can no longer answer "is this module here?" for anything spelled <code>foo.ko</code>.</p>
<h2>Exact change</h2>
<p>Add <code>patches/00NN-kern_linker-static-module-answers-EEXIST-for-kldname.patch</code>: in <code>linker_load_module()</code>, when <code>modname == NULL</code> and <code>linker_search_kld()</code> returns NULL, derive the module name from <code>linker_basename(kldname)</code> with a trailing <code>.ko</code> stripped and, if <code>modlist_lookup2(name, NULL) != NULL</code>, return <code>EEXIST</code> instead of <code>ENOENT</code>. This is what callers already handle, and it is semantically what stock FreeBSD returns when the file <em>is</em> found for an already-linked module ("Can't load more than one file with the same basename" -> <code>EEXIST</code>). No behaviour change when the file exists.</p>
<p>Also send the belt-and-braces fix upstream to <code>freebsd/virtual_oss</code> (main.c): <code>if (modfind("cuse") < 0 && kldload("cuse.ko") < 0 && errno != EEXIST)</code> — that also lets a non-root virtual_oss (which today gets <code>EPERM</code> from <code>priv_check(PRIV_KLD_LOAD)</code>, kern_linker.c:1210) start when cuse is present. Link the PR from this issue; do not wait on it.</p>
<h2>Acceptance criteria</h2>
<ul>
<li>[ ] Patch applies to releng/15.1, builds on amd64 and arm64, and is listed in <code>patches/</code> with the NextBSD prefix convention</li>
<li>[ ] Boot-test: a tiny C probe (<code>kldload("cuse.ko")</code>) returns -1/<code>EEXIST</code> on the VM; <code>kldload("nonexistent.ko")</code> still returns <code>ENOENT</code></li>
<li>[ ] Boot-test: <code>virtual_oss -f /dev/dsp0 -d dsp.test -t dsp.test.ctl</code> runs, <code>/dev/dsp.test</code> appears, <code>sndctl -f /dev/dsp.test</code> reports <code>from_user=1</code>, and <code>virtual_oss_cmd /dev/dsp.test.ctl</code> prints system info</li>
<li>[ ] Upstream PR to <code>freebsd/virtual_oss</code> opened and linked</li>
</ul>
<h2>Links</h2>
<ul>
<li>Epic nextbsd/nextbsd#473 · A1 · nextbsd/nextbsd-kernel#51</li>
<li><code>sys/kern/kern_linker.c:1210-1224, 2255-2282</code>; <code>usr.sbin/virtual_oss/virtual_oss/main.c:2554-2558</code> (releng/15.1)</li>
<li>Research: <code>e16/5-audio.md</code> section 1.2</li>
</ul></section>
<h3>Stage 1 — hand verification</h3>
<section id="K6" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">K6 · Phase 1: hand-verify the baked stack on real USB dongles (amd64 + Pi 500+ via RP1 xhci) and start the Bluetooth hardware matrix <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd/issues/477">nextbsd#477</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>documentation</code> <code>area:bluetooth</code> <code>needs-hardware</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>)</td></tr></table>
<h2>Problem</h2>
<h1>412 phase 1: "hccontrol, l2ping, sdpcontrol by hand. Prove the stack works before wrapping it." After K1 everything above USB enumeration is reasoned from source, never executed — the WLAN plan's honesty clause applies verbatim. No daemon should be written against an unproven kernel path.</h1>
<h2>Change</h2>
<p>Run the recipe below on (a) an amd64 laptop or desktop with a class-E0 dongle (CSR8510 <code>0a12:0001</code> is the zero-firmware baseline), (b) the Pi 500+ with the same dongle in an RP1 xhci port (the onboard radio is parked, K8), and (c) once K3/K4 exist, an Intel 8265/9560/AX200 laptop and a Realtek 8761BU dongle. Record everything in a new "Bluetooth hardware matrix" section on the plans site (the WLAN plan's §9 table is the template), with kernel/userland SHAs.</p>
<pre><code>usbconfig; dmesg | grep ubt; ngctl list # ubt0 on uhubN; node ubt0 (type ubt)
# graph, verbatim from libexec/rc/rc.d/bluetooth bluetooth_setup_stack()
ngctl mkpeer ubt0: hci hook drv; ngctl name ubt0:hook ubt0hci
ngctl mkpeer ubt0hci: l2cap acl hci; ngctl name ubt0hci:acl ubt0l2cap
ngctl connect ubt0hci: btsock_hci_raw: raw ubt0raw
ngctl connect ubt0l2cap: btsock_l2c_raw: ctl ubt0ctl
ngctl connect ubt0l2cap: btsock_l2c: l2c ubt0l2c
# controller up
hccontrol -n ubt0hci reset
hccontrol -n ubt0hci read_bd_addr # the real proof: a non-zero BD_ADDR
hccontrol -n ubt0hci read_local_version_information
hccontrol -n ubt0hci read_local_supported_features
hccontrol -n ubt0hci read_buffer_size
hccontrol -n ubt0hci write_scan_enable 3
hccontrol -n ubt0hci write_class_of_device 0x1c0104
hccontrol -n ubt0hci change_local_name nextbsd
hccontrol -n ubt0hci initialize; hccontrol -n ubt0hci read_node_state # "up"
# the world
hccontrol -n ubt0hci inquiry
hccontrol -n ubt0hci remote_name_request <addr> 0 0 0
l2ping -a <addr> # result=0
sdpcontrol -a <addr> browse # service records from a phone/headset
# teardown
ngctl shutdown ubt0hci:; ngctl shutdown ubt0l2cap:
</code></pre>
<p>Note what <code>hccontrol read_local_version_information</code> reports (HCI/LMP version) per dongle — it decides what BLE work is even possible later.</p>
<h2>Acceptance</h2>
<ul>
<li>[ ] Matrix section published with at least rows for: CSR dongle/amd64, CSR dongle/Pi 500+ (RP1 xhci), and a Broadcom/Apple vendor-class part if a Mac is available; each with the <code>read_bd_addr</code>, <code>inquiry</code>, <code>l2ping</code>, <code>sdpcontrol browse</code> outcome</li>
<li>[ ] Any kernel-side failure found becomes its own nextbsd-kernel ticket with <code>area:bluetooth</code></li>
<li>[ ] The recipe above is copied into the plan page as the canonical phase-1 procedure, so area 2 can encode it in <code>bluetoothd</code></li>
<li>[ ] Epic #473 gets a comment linking the matrix and stating the onboard Pi radio is parked (K8)</li>
</ul>
<h2>Related</h2>
<ul>
<li>nextbsd/nextbsd#412 phases 0–1, #473</li>
<li>K1, K3, K4; nextbsd-wlan-plan.html "Phase 1 — prove the chain by hand"</li>
</ul></section>
<section id="B4" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">B4 · Spike: hand-verify FreeBSD 15.1's LE path on NextBSD hardware with FreeBSD-BLE (scan, connect, SMP pair, HOGP mouse) and record the controller matrix <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd/issues/478">nextbsd#478</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill warn">Needs answer</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>question</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>)</td></tr></table>
<h2>Why</h2>
<p>The LE decision (B1) rests on the kernel's 2015-era LE code being usable: <code>LE_Create_Connection</code> via socket <code>connect()</code> with an LE address type, ATT on the CID-4 socket, SMP on CID-6, <code>SO_L2CAP_ENCRYPTED</code>, encryption-change propagation. It has been exercised by exactly one out-of-tree prototype, and the FreeBSD forum thread "The current state of BT-LE?" (2024-11 .. 2025-02) reports ATT timeouts against an MX Master 3S. Before B5/B6 are sized, run the prototype on the hardware NextBSD will bless and write down what actually works. This is the WLAN-plan "phase 1 hand-verification" for LE.</p>
<h2>Exact steps</h2>
<ol>
<li>Build <code>rhaberkorn/FreeBSD-BLE</code> branch <code>improvements</code> (has <code>hid-pair.sh</code>, random-address support) on a NextBSD kernel with <code>ng_bluetooth</code>, <code>ng_hci</code>, <code>ng_l2cap</code>, <code>ng_btsocket</code>, <code>ng_ubt</code> baked in (K ticket). Note: no licence file - <strong>do not vendor</strong>, run only.</li>
<li><code>hccontrol -n ubt0hci le_enable enable; le_read_buffer_size -v 2; le_read_local_supported_features</code> on each controller: CSR 8510 dongle, Intel AX200/AX210 (<code>iwmbtfw</code>), Realtek 8852 (<code>rtlbtfw</code>). Record LE ACL buffer count vs BR/EDR count (feeds B5).</li>
<li><code>le_enable</code> scan; <code>le_enable <addr></code> to dump attributes of: an MX Master 3S (BLE edition), a Keychron/Surface keyboard, a phone advertising, a heart-rate strap or Micro:bit if available.</li>
<li><code>lepair</code> + <code>lesecd</code> + <code>lehid</code> for the mouse: does the cursor move; does it survive the peripheral's connection-parameter-update request (kernel ACKs but never applies it, <code>ng_l2cap_cmds.c:224-226</code>); does it reconnect after power-cycling the mouse (peripheral-initiated, LTK request path via raw HCI).</li>
<li><code>hcidump</code>/<code>btsnoop</code> traces attached for each device; note any <code>ng_l2cap</code> panics or <code>ng_hci</code> "could not send" logs.</li>
</ol>
<h2>Acceptance criteria</h2>
<ul>
<li>[ ] Table in the ticket: controller x {LE scan, central connect, SMP legacy pair, encryption, HOGP mouse, reconnect} with pass/fail and trace links</li>
<li>[ ] Answer: is the LE buffer pool separate from ACL on the Intel/Realtek parts (yes/no + numbers)</li>
<li>[ ] Answer: does any device require LE Secure Connections (P-256) to pair, or is legacy SMP enough for MVP</li>
<li>[ ] Answer: does the MX Master 3S ATT timeout reproduce, and is it an MTU-exchange ordering issue (fixable in the userland host) or a kernel drop</li>
<li>[ ] Licence request sent to takawata@ for FreeBSD-BLE (BSD-2), outcome recorded on B6</li>
</ul>
<h2>Links</h2>
<ul>
<li>https://github.com/takawata/FreeBSD-BLE · https://github.com/rhaberkorn/FreeBSD-BLE/tree/improvements</li>
<li>FreeBSD forum t=95598 (state of BT-LE), t=99203 (Direct-BT port interest)</li>
<li>Research note §1.1-1.2</li>
</ul></section>
<h3>Stage 2 — bluetoothd core</h3>
<section id="D1" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">D1 · bluetoothd v0 skeleton: launchd job, Mach service, no-stack/no-adapter idle, `bluetooth status`, CI markers <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/206">nextbsd-userland#206</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5">—</td></tr></table>
<p>Parent: nextbsd/nextbsd#473 (E16). Seed: nextbsd/nextbsd#412. Area 3 notes: <code>e16/3-bluetoothd-cli.md</code> §1, §4.1, §7, §8.</p>
<h2>Why</h2>
<p>Every later Bluetooth ticket (adapter lifecycle, scan, pairing, HID, audio) needs a daemon that already boots under launchd, holds <code>org.nextbsd.bluetooth</code>, and passes CI on a machine with no radio and, today, no netgraph in the kernel. wland showed that the skeleton is where the boot-order and <code>/var/run</code> races live (userland#48, #49), so land it first and alone. wland also shipped without any boot-test gate and is still <code>UNPROBED</code> in <code>wedge-check.sh:153,156</code>; bluetoothd must not repeat that.</p>
<h2>Exact change</h2>
<p>Copy the wland layout one-for-one (<code>src/WLAN/</code> → <code>src/Bluetooth/</code>):</p>
<ul>
<li><code>src/Bluetooth/bluetoothd.c</code> — main loop shaped like <code>wland.c:472-655</code>: signal handlers, <code>ensure_run_dirs()</code> (<code>/var/run/bluetoothd</code>, re-created on every attempt, <code>wland.c:284-296</code>), Mach service started <strong>before</strong> any hardware work (<code>wland.c:499-505</code>), SCDynamicStore opened lazily and NULL tolerated (<code>wland.c:507-515</code>), 1 s poll tick, 2 s adapter rescan (<code>wland.c:93-99</code>).</li>
<li><code>src/Bluetooth/adapter.c</code> — v0 only detects whether the stack exists: <code>socket(PF_BLUETOOTH, SOCK_RAW, BLUETOOTH_PROTO_HCI)</code>; <code>EPROTONOSUPPORT</code> → log <code>BT-NOSTACK: ng_btsocket absent — idling</code> and stop polling (the <code>VAP_NO_NET80211</code> rule, <code>vap.h:35-43</code>, <code>wland.c:526</code>, <code>:620-625</code>); success with zero <code>ubt</code> nodes → <code>BT-NOADAPTER</code> and keep polling. Real adapter bring-up is D2.</li>
<li><code>src/Bluetooth/mach_service.c/.h</code> — verbatim copy of <code>src/WLAN/mach_service.c</code> with the service name <code>org.nextbsd.bluetooth</code>, marker <code>BT-RPC-OK</code>.</li>
<li><code>src/Bluetooth/bluetooth.defs</code> + <code>bluetooth_mig_types.h</code> — subsystem 31000; v0 carries <code>bt_adapter_count</code>, <code>bt_adapter_info</code>, <code>bt_stack_state</code> only, all fixed-size (<code>wlan.defs:10-16</code> OOL rule). Full surface grows in D2–D8; the enums (<code>bt_status_t</code> etc.) are defined here in full so later tickets only append routines.</li>
<li><code>src/Bluetooth/bluetoothd_mig.c</code> — routine bodies under <code>bluetoothd_lock()</code>.</li>
<li><code>src/Bluetooth/bluetooth.c</code> — the CLI, pure C, <code>bootstrap_look_up</code>, v0 verbs <code>status</code> and <code>list</code> (adapters only). Output: <code>no Bluetooth adapters</code> / <code>stack: absent</code>, exit 0.</li>
<li><code>src/Bluetooth/Makefile</code> — copy of <code>src/WLAN/Makefile</code> (bsd.prog.mk, <code>MIGOUT=</code>, <code>WARNS=0</code>, <code>-fblocks</code>, link line <code>-llaunch -lsystem_kernel -lSystemConfiguration -lCoreFoundation -lsystem_dispatch -l:libsystem_blocks.so</code>, <code>BINDIR=/usr/sbin</code>), <code>MAN= bluetoothd.8 bluetooth.8</code>.</li>
<li><code>overlay/System/Library/LaunchDaemons/org.nextbsd.bluetoothd.plist</code> — <code>RunAtLoad</code>, <code>KeepAlive</code>, <code>MachServices {org.nextbsd.bluetooth}</code>, stderr to <code>/var/log/bluetoothd.stderr</code>; header comment explains why <code>org.nextbsd.*</code> (same text as wland's plist) and why it always runs (no device-triggered launch exists on NextBSD).</li>
<li><code>build-userland.sh</code> — a <code>comp "bluetoothd"</code> block after the WLAN block (<code>:740-778</code>): host <code>mig</code> over <code>bluetooth.defs</code>, <code>make ... MIGOUT=</code>, then hand-link <code>/usr/sbin/bluetooth</code> from <code>bluetooth.c</code> + <code>bluetoothUser.c</code> with <code>-llaunch -lsystem_kernel</code> only.</li>
<li><code>overlay/usr/tests/freebsd-launchd-mach/run.sh</code> — after the ipconfig block: <code>timeout 15 bluetooth status</code> → <code>BT-CLI-OK</code>/<code>BT-CLI-FAIL</code>; <code>cat /var/log/bluetoothd.stderr</code> so <code>BT-RPC-OK</code> and <code>BT-NOSTACK</code>/<code>BT-NOADAPTER</code> reach the console.</li>
<li><code>overlay/usr/tests/freebsd-launchd-mach/wedge-check.sh</code> — <code>probe "org.nextbsd.bluetooth" "bluetooth status" bluetooth status</code>.</li>
<li><code>nextbsd/tests/boot-test.sh</code> — expect <code>BT-RPC-OK</code> and <code>BT-CLI-OK</code> (FAIL if absent); <code>BT-NOSTACK</code>/<code>BT-NOADAPTER</code> informational. (Separate PR in nextbsd/nextbsd, same ticket.)</li>
<li><code>bluetoothd.8</code> / <code>bluetooth.8</code> stubs with NAME/SYNOPSIS/DESCRIPTION/FILES; filled in by D6.</li>
<li>Check that the base image ships <code>libbluetooth</code>, <code>libnetgraph</code>, <code>libsdp</code>, <code>sdpd</code>, <code>bthidd</code>, <code>hccontrol</code> (FreeBSD <code>MK_BLUETOOTH</code>/<code>MK_NETGRAPH</code> default yes; NextBSD's <code>src.conf</code> not yet inspected). Record the answer in the plan; if absent, file a follow-up before D2.</li>
<li>If a <code>hcsecd</code> process exists at startup, log <code>BT-SEC-CONFLICT</code> (two link-key responders race; see D4).</li>
</ul>
<h2>Acceptance</h2>
<ul>
<li>[ ] <code>launchctl list</code> on the CI image shows <code>org.nextbsd.bluetoothd</code> with a live PID; <code>daemon-state.sh</code> passes without edits</li>
<li>[ ] <code>/var/log/bluetoothd.stderr</code> contains <code>BT-RPC-OK</code> and exactly one of <code>BT-NOSTACK</code> (pre-K kernel) or <code>BT-NOADAPTER</code> (post-K kernel)</li>
<li>[ ] <code>bluetooth status</code> exits 0 within 15 s on the CI image and prints <code>no Bluetooth adapters</code> or <code>stack: absent</code>; <code>run.sh</code> emits <code>BT-CLI-OK</code>; <code>boot-test.sh</code> gates on <code>BT-RPC-OK</code> and <code>BT-CLI-OK</code></li>
<li>[ ] <code>wedge-check.sh</code> probes <code>org.nextbsd.bluetooth</code>; it is not in <code>UNPROBED</code></li>
<li>[ ] The wired <code>em0</code> boot-test markers (IPCFG-*) are unchanged</li>
<li>[ ] amd64 and arm64 both build; no <code>.m</code> files, no CMake, no <code>-ldispatch</code>/<code>-lBlocksRuntime</code></li>
<li>[ ] Base-image availability of <code>libbluetooth</code>/<code>libnetgraph</code>/<code>sdpd</code>/<code>bthidd</code> is recorded in the PR description</li>
</ul>
<h2>Links</h2>
<p>https://pkgdemon.github.io/nextbsd-wlan-plan.html §7.1 (the daemon recipe) · <code>src/WLAN/wland.c</code>, <code>src/WLAN/mach_service.c</code>, <code>src/WLAN/Makefile</code>, <code>overlay/System/Library/LaunchDaemons/org.nextbsd.wland.plist</code>, <code>build-userland.sh:740-778</code>, <code>overlay/usr/tests/freebsd-launchd-mach/wedge-check.sh:80-156</code>, <code>run.sh:1512-1520</code></p></section>
<section id="B2" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">B2 · bluetoothd: engine interface (engine.h) that Classic and LE both implement - typed addresses, one pairing-prompt shape, engine-neutral bond record <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/204">nextbsd-userland#204</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5">—</td></tr></table>
<h2>Why</h2>
<p><code>bluetoothd</code>'s policy layer (adapter lifecycle, discovery list, pairing UX, SCPreferences persistence, SCDynamicStore publication, the MIG surface for <code>bluetooth(8)</code>) must not know whether a device is BR/EDR or LE. If the Classic engine is written first with Classic-only types (6-byte <code>bdaddr_t</code>, 16-byte link key, PIN-only prompts), adding LE later means touching every layer. WLAN avoided this by putting a narrow engine contract in <code>src/WLAN/supplicant.h</code> (opaque engine, <code>event_fd</code>, <code>pump_events</code> returning "state changed", caller-owned caches); do the same here, but for two engines.</p>
<h2>Exact change</h2>
<p>New <code>src/Bluetooth/engine.h</code> (name to match area D's layout), contents per the research note §4.2:</p>
<ul>
<li><code>struct bt_addr { uint8_t b[6]; enum { BREDR, LE_PUBLIC, LE_RANDOM } type; }</code> - identity everywhere (CLI, store keys, dynamic-store paths). Maps 1:1 onto <code>BDADDR_BREDR/BDADDR_LE_PUBLIC/BDADDR_LE_RANDOM</code> (<code>ng_bluetooth.h:228-229</code>).</li>
<li><code>struct bt_found</code> - name, RSSI, class-of-device (Classic), appearance (LE), raw EIR/AD bytes (<=240, what the kernel neighbor cache already stores, <code>ng_hci.h:632-634</code>), and <code>bredr</code>/<code>le</code> seen-flags so a dual-mode device merges into one row.</li>
<li><code>struct bt_pair_prompt { kind: PIN | PASSKEY_ENTRY | NUMERIC_CONFIRM | DISPLAY_PASSKEY; passkey }</code> - one shape for legacy PIN, SSP and LE SMP; <code>enum bt_pair_io</code> for the local IO capability the UI can offer.</li>
<li><code>struct bt_bond { addr; kind BREDR|LE; link_key[16]; ltk[16], irk[16], csrk[16], ediv, rand, key_size, authenticated, secure_conn }</code> - the SCPreferences record for both engines.</li>
<li><code>struct bt_engine_ops { attach, detach, event_fd, pump, discover, found_count/found_get, pair, pair_reply, connect, disconnect, bond_export, bond_import, profiles }</code> plus an event queue (<code>FOUND, PAIR_PROMPT, PAIRED, PAIR_FAILED, CONNECTED, DISCONNECTED, BOND_UPDATED</code>).</li>
<li>LE-only extras (GATT discover/read/write/notify) go in a separate <code>struct bt_le_ops</code> reachable via <code>bt_engine_le()</code>, consumed by the HOGP bridge (area H), never by the policy layer.</li>
<li>Both engines share one raw HCI socket per adapter (<code>ng_btsocket_hci_raw</code>), one <code>SO_HCI_RAW_FILTER</code> union mask, and a dispatcher keyed on event code; the LE engine adds three adapter bring-up commands (<code>Write_LE_Host_Supported</code>, <code>LE_Set_Event_Mask</code> <strong>without</strong> subevent 0x0a, <code>Set_Event_Mask | LE_META</code>) - what <code>hccontrol le_enable</code> does (<code>le.c:334-361</code>).</li>
</ul>
<h2>Acceptance criteria</h2>
<ul>
<li>[ ] <code>engine.h</code> committed with the types above and a header comment explaining the two-engine rule and the WLAN precedent</li>
<li>[ ] Classic engine (B3) compiles against it with no Classic-specific type leaking into <code>bluetoothd.c</code>/MIG code</li>
<li>[ ] A stub LE engine (<code>le_engine.c</code> returning ENOTSUP) registers through the same table, proving the policy layer is engine-agnostic</li>
<li>[ ] SCPreferences schema documented for <code>bt_bond</code> with both key families; <code>bond_import</code> at startup restores Classic link keys and LE LTKs before the first connection</li>
<li>[ ] <code>bluetooth(8)</code> prints addresses as <code>AA:BB:CC:DD:EE:FF</code> for BR/EDR and <code>AA:..:FF/le</code> or <code>/le-random</code> for LE</li>
</ul>
<h2>Links</h2>
<ul>
<li>Template: <code>nextbsd-userland/src/WLAN/supplicant.h</code>, <code>wland.h</code>, <code>wlan.defs</code></li>
<li>Research note §4.2 (engine interface), §4.3 (how LE slots in)</li>
<li>Depends on area D's <code>bluetoothd</code> skeleton ticket for file placement</li>
</ul></section>
<section id="D2" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">D2 · bluetoothd: adapter lifecycle — detect ubtN, build the netgraph graph, initialise the controller, publish State:/Bluetooth/Adapter, power on/off <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/207">nextbsd-userland#207</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>L</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#D1">D1</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/206">nextbsd-userland#206</a>), <a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>), <a href="#B2">B2</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/204">nextbsd-userland#204</a>)</td></tr></table>
<p>Parent: nextbsd/nextbsd#473. Notes: <code>e16/3-bluetoothd-cli.md</code> §2, §4, §7.</p>
<h2>Why</h2>
<p>On FreeBSD a USB dongle is useless until <code>/etc/rc.d/bluetooth</code> (devd-triggered) has built the netgraph graph and run the HCI init sequence (<code>libexec/rc/rc.d/bluetooth</code>, <code>bluetooth_setup_stack</code>). <code>ng_ubt</code> does not do it itself (no <code>mkpeer</code> in <code>ng_ubt.c</code>). NextBSD has no rc.d and no devd (<code>README.md:31</code>), so <code>bt_devenum()</code> (<code>lib/libbluetooth/hci.c:691-720</code>) lists nothing forever. This is the VAP-clone problem again (<code>vap.h:1-19</code>, userland#46 "Nothing creates the VAP"), and it belongs to bluetoothd.</p>
<h2>Exact change</h2>
<p><code>src/Bluetooth/adapter.c/.h</code>, replacing D1's stub:</p>
<ul>
<li><strong>Detect</strong>: every 2 s, list netgraph nodes of type <code>ubt</code> via <code>libnetgraph</code> (<code>NgMkSockNode</code> + <code>NgSendMsg(NGM_GENERIC_COOKIE, NGM_LISTNODES)</code>). Idempotent adopt: if <code>ubtNhci</code> already exists (a bluetoothd restart), attach to it instead of rebuilding (<code>vap_find_existing()</code> rule, <code>vap.h:79-86</code>). Handle removal: a <code>recvfrom</code> error on the raw socket or the node vanishing marks the slot inactive and removes its store key.</li>
<li><strong>Build the graph</strong> in C, mirroring <code>bluetooth_setup_stack</code>: <code>mkpeer ubtN: hci hook drv</code>; <code>name ubtN:hook ubtNhci</code>; <code>mkpeer ubtNhci: l2cap acl hci</code>; <code>name ubtNhci:acl ubtNl2cap</code>; <code>connect ubtNhci: btsock_hci_raw: raw ubtNraw</code>; <code>connect ubtNl2cap: btsock_l2c_raw: ctl ubtNctl</code>; <code>connect ubtNl2cap: btsock_l2c: l2c ubtNl2c</code>.</li>
<li><strong>Initialise</strong> over a raw HCI socket bound to <code>ubtNhci</code> (<code>bt_devopen</code>, <code>bt_devreq</code>): <code>Reset</code> (retry ×3), <code>Read_BD_ADDR</code>, <code>Read_Local_Supported_Features</code>, <code>Read_Buffer_Size</code>, <code>Write_Class_Of_Device 0x000104</code>, <code>Change_Local_Name</code> (ComputerName from configd if published, else <code>hostname</code>), <code>Write_Scan_Enable 2</code> (page scan only), <code>Set_Event_Mask</code> = default ∪ SSP bits (<code>NG_HCI_EVMSK_IO_CAPABILITY_REQ|_RESP|USER_CONFIRMATION_REQ|USER_PASSKEY_REQ|SIMPLE_PAIRING_COMPL|USER_PASSKEY_NOTIFICATION</code>, <code>ng_hci.h:275-283</code>), <code>Write_Simple_Pairing_Mode 1</code> when <code>NG_HCI_LMP_SECURE_SIMPLE_PAIRING</code> (<code>ng_hci.h:118</code>) is set, then <code>NGM_HCI_NODE_INIT</code>. Log <code>BT-ADAPTER-OK: ubt0hci <bdaddr> ssp=<y|n></code>.</li>
<li><strong>Publish</strong> <code>State:/Bluetooth/Adapter/<node> = {Address, Name, Powered, Discoverable, Connectable, Scanning}</code> from the CF TU (<code>btstore.c</code>, D5's file; D2 adds the adapter half) and <code>notify_post("org.nextbsd.bluetooth.adapter")</code>.</li>
<li><strong>Power</strong>: <code>bt_adapter_power(name, on)</code> — off = disconnect all, <code>Write_Scan_Enable 0</code>, <code>Powered:false</code>, refuse scan/connect with <code>bt_status_powered_off_e</code>; on = re-enable scans. Persist under <code>Adapters/<bdaddr>/Powered</code> in <code>org.nextbsd.bluetoothd</code> prefs; honour it at bring-up. <code>bt_adapter_discoverable(name, on, seconds)</code> toggles inquiry scan with an auto-off timer.</li>
<li><strong>MIG</strong>: <code>bt_adapter_count</code>, <code>bt_adapter_info(index → name, addr, powered, discoverable)</code>, <code>bt_adapter_power</code>, <code>bt_adapter_discoverable</code> in <code>bluetooth.defs</code>; CLI <code>bluetooth status</code>, <code>bluetooth power on|off</code>, <code>bluetooth discoverable on|off [-t s]</code>.</li>
<li>Carry <code>src/Bluetooth/hci_compat.h</code> with the opcodes/events <code>ng_hci.h</code> lacks (<code>Write_Inquiry_Mode</code> 0x0045, events 0x22, 0x2f, 0x32, 0x34, 0x3b) until the K ticket upstreams them.</li>
</ul>
<h2>Acceptance</h2>
<ul>
<li>[ ] On a machine with a supported dongle: <code>bluetooth status</code> prints the adapter node, bdaddr, <code>powered: on</code> within 5 s of plugging in; <code>ngctl list</code> shows <code>ubt0hci</code>, <code>ubt0l2cap</code> connected to <code>btsock_*</code></li>
<li>[ ] <code>BT-ADAPTER-OK</code> in the log; <code>State:/Bluetooth/Adapter/ubt0hci</code> present (verified through <code>bluetooth status</code>, which reads the same data over MIG — there is no scutil)</li>
<li>[ ] Restarting bluetoothd adopts the existing graph (no second <code>hci</code> node); unplugging the dongle removes the store key and <code>bluetooth status</code> returns to <code>no Bluetooth adapters</code></li>
<li>[ ] <code>bluetooth power off</code> → controller stops answering pages (verified from a phone); <code>power on</code> restores; the setting survives a reboot</li>
<li>[ ] On the CI image (no dongle) behaviour is unchanged from D1: <code>BT-NOADAPTER</code>, <code>BT-CLI-OK</code></li>
<li>[ ] Log line proves which of SSP / legacy-only the controller reports (<code>ssp=y|n</code>)</li>
</ul>
<h2>Links</h2>
<p><code>libexec/rc/rc.d/bluetooth</code> (<code>bluetooth_setup_stack</code>), <code>lib/libnetgraph/netgraph.h:48-60</code>, <code>lib/libbluetooth/hci.c:54-76,691-720</code>, <code>sys/netgraph/bluetooth/include/ng_hci.h:118,275-283,1015-1022,1423-1428</code>, <code>src/WLAN/vap.h</code>, <code>src/WLAN/wland.c:421-470</code>, <code>src/DiskArbitration/da_iokit_subscribe.c</code> (event-driven alternative, follow-up)</p>
<p>Implements its part of the Classic engine behind the <code>engine.h</code> interface (B2).</p></section>
<section id="D3" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">D3 · bluetoothd: Classic inquiry scan with cached results and remote names; `bluetooth scan` <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/208">nextbsd-userland#208</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#D2">D2</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/207">nextbsd-userland#207</a>)</td></tr></table>
<p>Parent: nextbsd/nextbsd#473. Notes: <code>e16/3-bluetoothd-cli.md</code> §5, §5.1.</p>
<h2>Why</h2>
<p>Pairing starts with the user picking a device from a list. Scan results cannot cross MIG as a plist (OOL is broken, <code>wlan.defs:10-16</code>) nor sit in the dynamic store (<code>CONFIG_DATA_MAX</code> 8192, <code>config_types.h:74</code>), so bluetoothd keeps a per-adapter cache and hands it out one entry per RPC, exactly as <code>wlan_scan_count</code>/<code>wlan_scan_entry</code> do (<code>wland_mig.c:110-156</code>).</p>
<h2>Exact change</h2>
<ul>
<li><code>src/Bluetooth/hci.c/.h</code> — the raw-socket event loop (poll fd per adapter, in the main <code>poll()</code> set like <code>supplicant_event_fd</code>, <code>wland.c:544-582</code>). <code>hci_scan_start(adapter, seconds)</code>: <code>Inquiry</code> (GIAC <code>0x9e8b33</code>, length = seconds/1.28, unlimited responses); collect <code>Inquiry_Result</code> (0x02) and, if <code>Write_Inquiry_Mode 1</code> was accepted at init, <code>Inquiry_Result_with_RSSI</code> (0x22); on <code>Inquiry_Complete</code> mark <code>scanning=0</code>, then issue <code>Remote_Name_Request</code> sequentially for entries without a cached name (<code>Remote_Name_Request_Complete</code> 0x07). Cache: <code>struct bt_scan_entry { bdaddr, name[249], cod, rssi, last_seen }</code>, max 64 per adapter, entries older than 5 min dropped on the next scan. Names are cached across scans by bdaddr.</li>
<li><code>bt_scan(name, seconds)</code> returns as soon as the inquiry is <strong>requested</strong> (<code>wlan.defs</code> comment on <code>wlan_scan</code>); <code>bt_scan_count(name → count, scanning)</code>; <code>bt_scan_entry(name, i → addr, devname, cod, rssi, paired)</code>.</li>
<li><code>notify_post("org.nextbsd.bluetooth.scan")</code> when the cache changes.</li>
<li>CLI <code>bluetooth scan [-t seconds] [adapter]</code>: request, poll <code>bt_scan_count.scanning</code> until 0 (max seconds+5), then print <code>ADDRESS NAME CLASS SIGNAL PAIRED</code> with the <code>wlan.c:110-122</code> signal bar; class rendered from CoD major/minor (keyboard, mouse, headset, phone, computer, …). No fixed <code>sleep(3)</code> — that is the wart <code>wlan.8</code> BUGS records.</li>
<li>Refuse with <code>bt_status_powered_off_e</code> / <code>bt_status_busy_e</code> as appropriate.</li>
</ul>
<h2>Acceptance</h2>
<ul>
<li>[ ] <code>bluetooth scan</code> on real hardware lists a phone in discoverable mode with its name within ~15 s; a second scan is faster (names cached)</li>
<li>[ ] A scan that finds nothing prints <code>no devices found</code> and exits 0</li>
<li>[ ] <code>bluetooth scan</code> while powered off prints <code>bluetooth: scan: adapter is powered off</code>, exit 1</li>
<li>[ ] Two concurrent <code>bluetooth scan</code> invocations: the second gets <code>busy</code> or joins the running inquiry; neither hangs the Mach service (wedge probe still answers during a scan)</li>
<li>[ ] CI image: <code>bluetooth scan</code> with no adapter prints <code>no Bluetooth adapters</code>, exit 1, within 15 s</li>
</ul>
<h2>Links</h2>
<p><code>src/WLAN/wlan.defs</code> (<code>wlan_scan*</code>), <code>src/WLAN/wland_mig.c:110-156</code>, <code>src/WLAN/supplicant.h:33-39</code>, <code>ng_hci.h:697,838,1866-1871,1915</code>, <code>lib/libbluetooth/bluetooth.h:157-186</code> (<code>bt_devinquiry</code>, <code>bt_devremote_name</code> as reference implementations)</p>
<p>Implements its part of the Classic engine behind the <code>engine.h</code> interface (B2).</p></section>
<section id="D5" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">D5 · bluetoothd: SCPreferences persistence — PairedDevices metadata plus a separate 0600 link-key file; `bluetooth list` <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/210">nextbsd-userland#210</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#D1">D1</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/206">nextbsd-userland#206</a>)</td></tr></table>
<p>Parent: nextbsd/nextbsd#473. Notes: <code>e16/3-bluetoothd-cli.md</code> §6.</p>
<h2>Why</h2>
<p>"Keep it paired across reboots" is the E16 goal statement. Link keys are 16-byte secrets, there is still no keychain (keychain plan §4.G "interim", Q1 "first consumer"), and WLAN already chose plaintext PSKs in a root-owned SCPreferences file as acknowledged debt (<code>src/WLAN/airport.h:40-48</code>, https://pkgdemon.github.io/nextbsd-wlan-plan.html Q2). Bluetooth repeats that decision, with one improvement: the secrets live in their own prefs file behind one function, so the keychain migration later moves one file and changes one function, and non-secret device metadata stays world-readable for tooling.</p>
<h2>Exact change</h2>
<p><code>src/Bluetooth/btstore.c/.h</code> — the single CoreFoundation translation unit (the <code>airport.c:1-13</code> rule), holding both the SCDynamicStore publish helpers used by D2/D4/D8 and the SCPreferences code:</p>
<ul>
<li>App ID <code>org.nextbsd.bluetoothd</code> → <code>/Local/Library/Preferences/SystemConfiguration/org.nextbsd.bluetoothd.plist</code>:</li>
<li><code>PairedDevices = { "<addr>" = { Name, Class (int), Adapter (local bdaddr), Paired (unix time), LastSeen, AutoConnect (bool), Trusted (bool), Profiles (array of strings, e.g. "HID") } }</code></li>
<li><code>Adapters = { "<bdaddr>" = { Powered, Discoverable, Name } }</code></li>
<li>App ID <code>org.nextbsd.bluetoothd.keys</code> → <code>...org.nextbsd.bluetoothd.keys.plist</code>:</li>
<li><code>LinkKeys = { "<addr>" = { Key = <CFData 16 bytes>, Type = <int, HCI key_type> } }</code>; the name <code>LongTermKeys</code> is reserved for the B area.</li>
<li>API: <code>bt_dev_save/find/forget/count/at</code>, <code>bt_adapter_pref_get/set</code>, <code>bt_keys_save/find/forget</code>. Every save commits immediately (<code>SCPreferencesSetValue</code> + <code>SCPreferencesCommitChanges</code>, temp-file + rename as <code>airport.c:276-293</code>).</li>
<li>Permissions: <code>umask(077)</code> at daemon start and <code>chmod(path, 0600)</code> after <strong>every</strong> commit of the keys file (rename yields a new inode, and whether SCPreferences honours umask is unverified). The metadata file stays 0644.</li>
<li>Keys are never formatted into log lines.</li>
<li>MIG: <code>bt_paired_count</code>, <code>bt_paired_entry(i → addr, devname, cod, state, autoconnect)</code>; CLI <code>bluetooth list</code> (<code>ADDRESS NAME CLASS STATE AUTO</code>).</li>
<li><code>bluetoothd.8</code> FILES section documents both paths and states plainly that link keys are stored in plaintext.</li>
</ul>
<h2>Acceptance</h2>
<ul>
<li>[ ] A <code>bt_dev_save</code> + <code>bt_keys_save</code> pair from a unit-style test binary (run in <code>run.sh</code>, marker <code>BT-PREFS-OK</code>) round-trips through a bluetoothd restart on the CI image with no adapter: <code>bluetooth list</code> shows the entry, the keys file is <code>-rw------- root</code></li>
<li>[ ] <code>bt_keys_forget</code> removes only the key; <code>bt_dev_forget</code> removes only the metadata; each file is valid XML plist afterwards (parseable by <code>plutil</code>-equivalent or CFPropertyList round-trip in the test)</li>
<li>[ ] Corrupt or missing prefs files are tolerated: bluetoothd logs and starts with an empty table (never crashes on startup because of prefs)</li>
<li>[ ] <code>grep -c</code> of any 32-hex-char string in <code>/var/log/bluetoothd.stderr</code> after a pairing (D4) is 0</li>
<li>[ ] Man page states the plaintext debt and points at the keychain plan</li>
</ul>
<h2>Links</h2>
<p><code>src/WLAN/airport.c:230-430</code>, <code>src/WLAN/airport.h:32-48</code>, <code>usr.sbin/bluetooth/hcsecd/parser.y:300-390</code> (the hcsecd.keys format it replaces), https://pkgdemon.github.io/freebsd-keychain-port-plan.html</p></section>
<section id="D4" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">D4 · bluetoothd: security manager replacing hcsecd — link-key/PIN replies, SSP (numeric comparison, passkey), pair/unpair RPCs, pull-model user confirmation <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/209">nextbsd-userland#209</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>L</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#D2">D2</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/207">nextbsd-userland#207</a>), <a href="#D5">D5</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/210">nextbsd-userland#210</a>)</td></tr></table>
<p>Parent: nextbsd/nextbsd#473. Notes: <code>e16/3-bluetoothd-cli.md</code> §3.1, §3.3, §5.2, §5.3.</p>
<h2>Why</h2>
<p>FreeBSD's <code>hcsecd(8)</code> cannot be the key owner under bluetoothd:</p>
<ul>
<li>it stores a new link key only for a device already listed in <code>/etc/bluetooth/hcsecd.conf</code> (<code>hcsecd.c:392-396</code>, <code>get_key(.., exact_match=1)</code>), so a device paired at runtime loses its key;</li>
<li>it flushes keys to <code>/var/db/hcsecd.keys</code> only on SIGHUP or exit (<code>hcsecd.c:202,423</code>);</li>
<li>it handles exactly three events and logs everything else as an error (<code>hcsecd.c:124-127,190-193</code>) — no Secure Simple Pairing, which every phone and most keyboards made after 2009 require;</li>
<li>it answers <code>PIN_Code_Request</code> from a static file and cannot ask anyone;</li>
<li>and two raw HCI sockets both receive <code>Link_Key_Request</code> (<code>ng_btsocket_hci_raw.c:500-517</code>), so running hcsecd next to bluetoothd would make both reply.</li>
</ul>
<p>The reply code is ~120 lines (<code>hcsecd.c:264-379</code>); reimplementing it over the same socket with a real key store behind it is smaller than any supervision scheme. The kernel already delivers every HCI event to the raw hook before processing it (<code>ng_hci_main.c:706-719</code>, <code>ng_hci_misc.c:63-78</code>) and defines the SSP events/replies bluetoothd needs (<code>ng_hci.h:865-907,2089-2103</code>); what nothing in base does is set the controller event mask and <code>Write_Simple_Pairing_Mode</code> (D2 does).</p>
<h2>Exact change</h2>
<p><code>src/Bluetooth/security.c/.h</code>:</p>
<ul>
<li>Register the raw socket filter for <code>PIN_CODE_REQ</code>, <code>LINK_KEY_REQ</code>, <code>LINK_KEY_NOTIFICATION</code>, <code>AUTH_COMPL</code>, <code>IO_CAPABILITY_REQUEST</code> (0x31), 0x32, <code>USER_CONFIRMATION_REQUEST</code> (0x33), 0x34, 0x36, 0x3b, plus the connection events (<code>bt_devfilter_evt_set</code>).</li>
<li><strong>Responder</strong>: <code>Link_Key_Request</code> → <code>Link_Key_Request_Reply</code> from <code>bt_keys_find()</code> else <code>_Negative_Reply</code>; <code>Link_Key_Notification</code> → <code>bt_keys_save()</code> immediately (D5); <code>PIN_Code_Request</code> → reply if a PIN was supplied to <code>bt_pair</code> or park in <code>awaiting_user(method=pin)</code>; <code>IO_Capability_Request</code> → <code>IO_Capability_Request_Reply(DisplayYesNo, no OOB, MITM required)</code> if we initiated a pairing with this bdaddr, else <code>IO_Capability_Request_Negative_Reply</code> (incoming pairings rejected in v0); <code>User_Confirmation_Request(numeric)</code> → park in <code>awaiting_user(method=numeric_comparison, passkey)</code> (auto-accept only when the peer is NoInputNoOutput <em>and</em> we initiated); <code>User_Passkey_Request</code> → <code>awaiting_user(method=passkey_entry)</code>; <code>Simple_Pairing_Complete</code>/<code>Authentication_Complete</code> → <code>done|failed</code>.</li>
<li><strong>Initiator</strong>: <code>bt_pair(addr, pin)</code> → <code>Create_Connection</code> (page-scan params from the scan cache) → <code>Authentication_Requested</code> → the state machine above; 60 s <code>awaiting_user</code> timeout sends the negative reply and fails with <code>pairing_timeout</code>.</li>
<li><strong>User prompt is pull, not push</strong> (there is no Mach-speaking UI and no per-user agent in the tree): on <code>awaiting_user</code>, set <code>State:/Bluetooth/Pairing/<addr> = {Method, Passkey, Expires}</code> and <code>notify_post("org.nextbsd.bluetooth.pairing")</code>; <code>bt_pair_status(addr → phase, method, passkey)</code>; <code>bt_pair_confirm(addr, accept, passkey)</code> sends <code>User_Confirmation_Request_Reply</code>/<code>_Negative_Reply</code> or <code>User_Passkey_Request_Reply</code>/<code>PIN_Code_Request_Reply</code>. Remove the <code>Pairing/</code> key on done/failed.</li>
<li>On success: <code>PairedDevices[addr]</code> written (name, class, adapter, time, <code>AutoConnect=true</code>, <code>Trusted=true</code>), <code>State:/Bluetooth/Device/<addr></code> published, <code>notify_post("org.nextbsd.bluetooth.device")</code>.</li>
<li><code>bt_unpair(addr)</code>: <code>bt_keys_forget</code>, <code>Delete_Stored_Link_Key</code> (<code>ng_hci.h:1090</code>), disconnect if connected, remove prefs entry and store key, notify.</li>
<li><code>/etc/bluetooth/hcsecd.conf</code> is never read; if a <code>hcsecd</code> process exists, log <code>BT-SEC-CONFLICT</code> and refuse to answer <code>Link_Key_Request</code> until it is gone (prevents a double reply).</li>
<li>Never log key bytes (hcsecd's "exists/doesn't exist" habit, <code>hcsecd.c:249-253</code>).</li>
<li>CLI (full verbs in D6; D4 lands the minimum): <code>bluetooth pair <addr> [pin]</code> interactive prompt <code>Confirm that 123456 is shown on <name> [y/N]</code>; <code>bluetooth confirm <addr> yes|no|<passkey></code>; <code>bluetooth unpair <addr></code>.</li>
</ul>
<h2>Acceptance</h2>
<ul>
<li>[ ] SSP numeric comparison with a phone: <code>bluetooth pair</code> shows the same 6 digits the phone shows; <code>y</code> completes; the phone lists the desktop as paired</li>
<li>[ ] SSP with a keyboard (passkey entry on the keyboard, <code>DisplayYesNo</code> on us) and legacy PIN with a 2000s-era device (PIN via argument) both complete</li>
<li>[ ] Answering <code>n</code>, or not answering for 60 s, fails cleanly (<code>pairing_rejected</code> / <code>pairing_timeout</code>), leaves no <code>Pairing/</code> key, and the adapter is usable immediately after</li>
<li>[ ] After a reboot, the paired device's <code>Link_Key_Request</code> is answered from the store — verified by reconnecting without pairing again</li>
<li>[ ] <code>bluetooth unpair</code> makes the next connection attempt from the device fail authentication (it must be re-paired)</li>
<li>[ ] An unsolicited pairing attempt from a phone is rejected and logged, not silently accepted</li>
<li>[ ] No <code>hcsecd</code> process runs on the image; <code>BT-SEC-CONFLICT</code> fires if one is started by hand</li>
</ul>
<h2>Links</h2>
<p><code>usr.sbin/bluetooth/hcsecd/hcsecd.c</code>, <code>sys/netgraph/bluetooth/hci/ng_hci_main.c:706-719</code>, <code>ng_hci_misc.c:63-78</code>, <code>ng_hci_evnt.c:107-126</code>, <code>sys/netgraph/bluetooth/include/ng_btsocket.h:71-74</code>, <code>ng_btsocket_hci_raw.c:500-517,704-716</code>, <code>ng_hci.h:275-283,813,865-907,1090,2089-2103</code>, <code>src/hostnamed/hostnamed.c:20</code> (notify_post precedent)</p>
<hr />
<h2>Engine notes (merged from E16 draft B3)</h2>
<p>This is the Classic engine behind <code>engine.h</code> (B2): inquiry/remote-name (D3) and legacy PIN + Secure Simple Pairing here share one raw HCI socket and event loop. B3's analysis follows.</p>
<h2>Why</h2>
<p>FreeBSD's Classic pairing daemon <code>hcsecd(8)</code> answers exactly three events - <code>PIN_Code_Request</code>, <code>Link_Key_Request</code>, <code>Link_Key_Notification</code> (<code>usr.sbin/bluetooth/hcsecd/hcsecd.c:123-126</code>) - i.e. <strong>legacy PIN pairing only</strong>. Since FreeBSD commit <code>4ae0fa8a2f</code> (2025-01-27, PR 265066) the kernel defines and passes through the Secure Simple Pairing events (<code>IO_Capability_Request</code> 0x31, <code>User_Confirmation_Request</code> 0x33, <code>Simple_Pairing_Complete</code> 0x36; <code>ng_hci_evnt.c:123-124</code>, <code>ng_hci.h:865-898, 2089-2094</code>) but no daemon in base uses them. Devices that require SSP (BT 2.1+ with no legacy fallback, "Secure Connections Only" mode) cannot pair on stock FreeBSD. Because <code>hcsecd</code> is ~500 lines with a yacc config, absorbing it into <code>bluetoothd</code>'s Classic engine costs less than supervising it and bolting SSP on beside it. (Unlike <code>wpa_supplicant</code>, there is nothing to preserve.)</p>
<h2>Exact change</h2>
<p><code>src/Bluetooth/classic_engine.c</code> implementing <code>bt_engine_ops</code> (B2):</p>
<ul>
<li>Open <code>socket(PF_BLUETOOTH, SOCK_RAW, BLUETOOTH_PROTO_HCI)</code>, bind to the <code>ubtNhci</code> node, set <code>SO_HCI_RAW_FILTER</code> for: Inquiry_Result(+RSSI, Extended), Inquiry_Complete, Remote_Name_Request_Complete, Connection_Complete/Disconnection_Complete, PIN_Code_Request, Link_Key_Request, Link_Key_Notification, IO_Capability_Request/Response, User_Confirmation_Request, User_Passkey_Request/Notification, Simple_Pairing_Complete, Authentication_Complete, Encryption_Change.</li>
<li>Bring-up: <code>Write_Simple_Pairing_Mode(1)</code>, <code>Write_Scan_Enable</code>, <code>Write_Class_of_Device</code>, <code>Write_Local_Name</code> (from <code>ComputerName</code> in SCPreferences), <code>Set_Event_Mask</code> including the SSP bits (<code>NG_HCI_EVMSK_IO_CAPABILITY_REQ</code> .. <code>_USER_PASSKEY_NOTIFICATION</code>, <code>ng_hci.h:275-283</code>).</li>
<li><code>discover()</code>: <code>Inquiry</code> (GIAP, 10.24 s) then <code>Remote_Name_Request</code> per result without EIR name; fill <code>bt_found</code> (CoD, EIR bytes, RSSI).</li>
<li><code>pair()</code>: initiate <code>Authentication_Requested</code> on an ACL (or <code>Create_Connection</code> first); answer <code>IO_Capability_Request</code> with the caller's <code>bt_pair_io</code>; surface <code>User_Confirmation_Request</code> (numeric comparison) / <code>User_Passkey_Request</code> / <code>PIN_Code_Request</code> as one <code>BT_EV_PAIR_PROMPT</code>; <code>pair_reply()</code> sends the matching <code>*_Reply</code> / <code>*_Negative_Reply</code> (OCFs 0x2b-0x2d, 0x34 for SSP; 0x0d/0x0e for PIN).</li>
<li>Link keys: <code>Link_Key_Notification</code> -> <code>bt_bond{kind=BREDR}</code> -> <code>BT_EV_BOND_UPDATED</code> (policy layer persists); <code>Link_Key_Request</code> answered from the in-memory bond table populated by <code>bond_import</code>.</li>
<li><code>profiles()</code>: SDP <code>ServiceSearchAttribute</code> via <code>libsdp</code> for HID (0x1124), A2DP sink (0x110b), HFP (0x111e), AVRCP (0x110e) - enough for the CLI and for area H/A to decide what to start.</li>
<li>Keep <code>hcsecd.conf</code> compatibility for one release: <code>bond_import</code> can read <code>/etc/bluetooth/hcsecd.conf</code> keys if present (migration), then the file is retired.</li>
</ul>
<h2>Acceptance criteria</h2>
<ul>
<li>[ ] <code>bluetooth scan</code> lists a Magic Keyboard and a Classic headset with names and CoD within one inquiry cycle</li>
<li>[ ] Legacy PIN pairing works with a fixed-PIN device (0000) and a keyboard that types the PIN</li>
<li>[ ] SSP numeric-comparison pairing works with a phone (both sides show the same 6 digits; <code>bluetooth pair --confirm</code>), and SSP just-works pairing with a headset</li>
<li>[ ] Link key persists in SCPreferences; after reboot, the device reconnects without a prompt and the login-window keyboard case is verified</li>
<li>[ ] <code>hcsecd</code> is not started by launchd; no <code>/var/run/hcsecd.pid</code></li>
<li>[ ] Unit test: HCI event parser exercised with captured <code>hcidump</code>-style frames for every filtered event</li>
</ul>
<h2>Links</h2>
<ul>
<li>FreeBSD SSP kernel commit: https://github.com/freebsd/freebsd-src/commit/4ae0fa8a2f (PR 265066 - <strong>check bugzilla for an unlanded hcsecd SSP patch</strong>; fetch was blocked during research)</li>
<li>Research note §1.3, §6 ("Classic pairing without SSP is a growing failure mode")</li>
</ul></section>
<section id="D7" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">D7 · bluetoothd: supervise stock sdpd (and the child-supervision hook bthidd/btpand will use) <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/212">nextbsd-userland#212</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#D2">D2</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/207">nextbsd-userland#207</a>)</td></tr></table>
<p>Parent: nextbsd/nextbsd#473. Notes: <code>e16/3-bluetoothd-cli.md</code> §2, §3.2.</p>
<h2>Why</h2>
<p><code>sdpd(8)</code> is the SDP server every profile daemon registers with over <code>/var/run/sdp</code> (<code>lib/libsdp/sdp.h:550</code>); without it a remote device cannot discover what the desktop offers, and <code>bthidd</code>/<code>btpand</code> fail to register. It stays stock — base FreeBSD, socket-driven, Mach-unaware — for the same reasons wpa_supplicant does (<code>wland.c:41-55</code>; userland#46). launchd cannot start it: it needs the L2CAP socket layer wired to an adapter, which only exists after D2, and there is no launchd job ordering. So bluetoothd spawns it, as wland spawns wpa_supplicant (<code>wland.c:249-282</code>).</p>
<h2>Exact change</h2>
<ul>
<li><code>src/Bluetooth/child.c/.h</code> — a small generic supervisor: <code>child_spawn(name, argv)</code> (fork/exec, <code>-d</code> no-detach so we reap), <code>child_reap()</code> from the main loop's <code>waitpid(-1, WNOHANG)</code> sweep (<code>wland.c:584-601</code>), <code>child_stop(name)</code> (SIGTERM, wait), restart with 1 s/2 s/4 s back-off capped at 30 s, <code>BT-CHILD-DIED: <name></code> log line. The same API is what the H (bthidd) and, if ever, PAN (btpand) tickets call.</li>
<li>Spawn <code>/usr/sbin/sdpd -d</code> when the first adapter reaches <code>BT-ADAPTER-OK</code>; stop it when the last adapter goes away; never run two.</li>
<li><code>SIGPIPE</code> ignored (<code>wland.c:492-493</code>); children inherit no Mach ports beyond bootstrap.</li>
<li>Shutdown order: children first, then the store keys, then the graph is left intact for adoption (the <code>wland.c:630-650</code> reasoning).</li>
</ul>
<h2>Acceptance</h2>
<ul>
<li>[ ] With a dongle: <code>sdpd</code> is running as a child of bluetoothd within 1 s of <code>BT-ADAPTER-OK</code>; <code>sdpcontrol -l browse</code> from another FreeBSD/Linux box lists the desktop's records once a profile registers</li>
<li>[ ] <code>kill -9 $(pgrep sdpd)</code> → restarted within 2 s, <code>BT-CHILD-DIED: sdpd</code> logged; ten kills in a row hit the back-off cap without spinning</li>
<li>[ ] Unplug the only dongle → sdpd is stopped; replug → started again</li>
<li>[ ] CI image (no adapter): no sdpd process, no restart loop, nothing in the log except the D1 markers</li>
</ul>
<h2>Links</h2>
<p><code>usr.sbin/bluetooth/sdpd/sdpd.8</code>, <code>sdpd/main.c:75-95</code> (<code>-d</code>, <code>-c</code>, <code>-u</code>, <code>-g</code>), <code>src/WLAN/wland.c:249-282,584-601</code></p></section>
<section id="D8" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">D8 · bluetoothd: connect/disconnect, per-device state publishing (State:/Bluetooth/Device), auto-reconnect of paired devices at boot <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/213">nextbsd-userland#213</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#D4">D4</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/209">nextbsd-userland#209</a>), <a href="#D5">D5</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/210">nextbsd-userland#210</a>)</td></tr></table>
<p>Parent: nextbsd/nextbsd#473. Notes: <code>e16/3-bluetoothd-cli.md</code> §5, §7.</p>
<h2>Why</h2>
<p>Pairing is worthless if the device does not come back after a reboot. On FreeBSD the ACL is either initiated by the peripheral paging us (page scan must be on and the link key answered — D2, D4) or by us (<code>Create_Connection</code>). bluetoothd owns the policy: reconnect <code>AutoConnect</code> devices when an adapter comes up, accept incoming ACLs from <code>Trusted</code> devices, and publish a compact per-device state that the pane, the H/A daemons and <code>bluetooth list</code> all read. This is the <code>AirPort{Authenticated}</code> equivalent for Bluetooth (<code>airport.h:9-25</code>).</p>
<h2>Exact change</h2>
<ul>
<li><code>src/Bluetooth/hci.c</code>: <code>Create_Connection</code>/<code>Disconnect</code> (<code>ng_hci.h:724,735</code>), track <code>Connection_Complete</code>/<code>Disconnection_Complete</code>/<code>Encryption_Change</code>/<code>Role_Change</code> per bdaddr; <code>Authentication_Requested</code> + <code>Set_Connection_Encryption</code> on every new ACL to a paired device so profile traffic is always on an encrypted link.</li>
<li>MIG: <code>bt_connect(addr)</code>, <code>bt_disconnect(addr)</code>, <code>bt_device_status(addr → devname, cod, state, rssi)</code>; <code>bt_connect</code> returns when <strong>requested</strong> (the <code>wlan_connect</code> rule) and the caller watches <code>bt_device_status</code>/<code>bluetooth list</code>.</li>
<li><code>State:/Bluetooth/Device/<addr> = {Name, Class, Adapter, Paired, Connected, Profiles}</code>, updated on every transition; <code>notify_post("org.nextbsd.bluetooth.device")</code>. Only paired or connected devices get a key (never scan results).</li>
<li>Policy: on <code>BT-ADAPTER-OK</code>, for each <code>PairedDevices[*].AutoConnect</code> bound to this adapter, attempt <code>Create_Connection</code> once with a 10 s spacing; incoming <code>Connection_Request</code> from a <code>Trusted</code> bdaddr is accepted, from anyone else rejected (<code>Reject_Connection_Request</code>), logged.</li>
<li><code>Read_RSSI</code> on connected devices every 10 s for <code>bt_device_status</code> (cheap; optional if the controller rejects it).</li>
<li><code>bluetooth connect|disconnect <addr></code> verbs.</li>
</ul>
<h2>Acceptance</h2>
<ul>
<li>[ ] Reboot with a paired Bluetooth keyboard powered on: <code>bluetooth list</code> shows it <code>connected</code> within 30 s of <code>BT-ADAPTER-OK</code> with no user action (the HID data path itself is the H ticket; this ticket proves the ACL + encryption)</li>
<li>[ ] <code>bluetooth disconnect</code> drops the ACL; the device reconnects when it pages us (keyboard keypress) because it is <code>Trusted</code></li>
<li>[ ] An unpaired device paging us is rejected and logged</li>
<li>[ ] <code>State:/Bluetooth/Device/<addr></code> transitions are visible through <code>bluetooth list</code> and <code>bluetooth status</code> (paired/connected counts) and each publish is under 1 KiB</li>
<li>[ ] CI image: nothing to connect; <code>bluetooth connect aa:bb:cc:dd:ee:ff</code> prints <code>no Bluetooth adapters</code>, exit 1</li>
</ul>
<h2>Links</h2>
<p><code>ng_hci.h:724,735,813,819</code>, <code>src/WLAN/airport.c:129-212</code>, <code>src/WLAN/wlan.defs</code> (<code>wlan_connect</code> returns-when-requested comment)</p></section>
<section id="D6" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">D6 · bluetooth(8): full CLI — status|list|scan|pair|confirm|unpair|connect|disconnect|power|discoverable, `--no-prompt` exit codes, man pages <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/211">nextbsd-userland#211</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#D1">D1</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/206">nextbsd-userland#206</a>), <a href="#D3">D3</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/208">nextbsd-userland#208</a>), <a href="#D4">D4</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/209">nextbsd-userland#209</a>), <a href="#D5">D5</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/210">nextbsd-userland#210</a>), <a href="#D8">D8</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/213">nextbsd-userland#213</a>)</td></tr></table>
<p>Parent: nextbsd/nextbsd#473. Notes: <code>e16/3-bluetoothd-cli.md</code> §9, §10.</p>
<h2>Why</h2>
<p>The CLI is two things, as <code>wlan(8)</code> is (<code>src/WLAN/wlan.c:14-40</code>): the only way to inspect Bluetooth state on a system with no <code>scutil</code>, and the desktop's bridge across the Mach line — no Gershwin process speaks Mach, so the preference pane will drive <code>bluetooth</code> via NSTask exactly as <code>Network.prefPane</code> drives its helper. D1–D5 and D8 each land their minimum verb; this ticket makes the surface complete, consistent, documented and scriptable.</p>
<h2>Exact change</h2>
<p><code>src/Bluetooth/bluetooth.c</code> (pure C, <code>-llaunch -lsystem_kernel</code> only) and <code>bluetooth.8</code>, <code>bluetoothd.8</code>:</p>
<pre><code>bluetooth status [adapter]
bluetooth list
bluetooth scan [-t seconds] [adapter]
bluetooth pair <addr> [pin] [--no-prompt]
bluetooth confirm <addr> yes|no|<passkey>
bluetooth unpair <addr>
bluetooth connect <addr>
bluetooth disconnect <addr>
bluetooth power on|off [adapter]
bluetooth discoverable on|off [-t seconds] [adapter]
</code></pre>
<ul>
<li>Output formats as in the notes §9 (<code>status</code> is key/value lines like <code>wlan status</code>; <code>list</code>/<code>scan</code> are fixed-width tables like <code>wlan scan</code>, <code>wlan.c:215-229</code>).</li>
<li>Exit codes: 0 ok · 1 error or RPC failure · 2 usage · 3 user answer needed (<code>pair --no-prompt</code> only, printing <code>method=<numeric_comparison|passkey_entry|pin> passkey=<n></code> on stdout so the pane can show it and call <code>confirm</code>).</li>
<li><code>pair</code> interactive: polls <code>bt_pair_status</code> every 250 ms, prompts on the tty, calls <code>bt_pair_confirm</code>, prints the outcome; honours Ctrl-C by sending <code>confirm no</code>.</li>
<li>Address argument accepts <code>aa:bb:cc:dd:ee:ff</code> or a unique name prefix from the paired list.</li>
<li><code>cannot reach org.nextbsd.bluetooth — is bluetoothd running?</code> on lookup failure (<code>wlan.c:360-366</code>); <code>status_str()</code> table for every <code>bt_status_t</code>.</li>
<li><code>bluetooth.8</code>: COMMANDS, EXIT STATUS, FILES (<code>/var/log/bluetoothd.stderr</code>, both prefs paths, <em>link keys are plaintext</em>), EXAMPLES (scan → pair with numeric comparison → list → unpair, in the style of <code>wlan.8</code> EXAMPLES), DIAGNOSTICS (<code>no Bluetooth adapters</code> → <code>ngctl list</code>; <code>stack: absent</code> → kernel lacks <code>ng_btsocket</code>; <code>busy</code>), SEE ALSO (<code>bluetoothd(8)</code>, <code>hccontrol(8)</code>, <code>sdpd(8)</code>, <code>bthidd(8)</code>), BUGS.</li>
<li><code>bluetoothd.8</code>: ARCHITECTURE diagram (as <code>wland.8</code>), why hcsecd is replaced, which children it supervises, the State:/ keys and notify names, FILES.</li>
<li><code>run.sh</code>: extend <code>BT-CLI-OK</code> to run every verb once on the adapterless image and assert the documented exit codes (<code>status</code>/<code>list</code> → 0; <code>scan</code>/<code>pair</code>/<code>connect</code> → 1 with <code>no Bluetooth adapters</code>; bad verb → 2).</li>
</ul>
<h2>Acceptance</h2>
<ul>
<li>[ ] Every verb above exists, is documented in <code>bluetooth.8</code>, and returns the documented exit code on the CI image (asserted by <code>run.sh</code>)</li>
<li>[ ] <code>bluetooth pair --no-prompt</code> + <code>bluetooth confirm</code> complete an SSP pairing on hardware without any tty interaction</li>
<li>[ ] <code>man bluetooth</code> and <code>man bluetoothd</code> render (mandoc lint clean, as <code>wlan.8</code>/<code>wland.8</code>)</li>
<li>[ ] The binary links only liblaunch + libsystem_kernel (<code>needed_check</code>-style assertion in <code>build-userland.sh</code>)</li>
<li>[ ] A short README section under <code>src/Bluetooth/</code> mirrors userland#47's WLAN section</li>
</ul>
<h2>Links</h2>
<p><code>src/WLAN/wlan.c</code>, <code>src/WLAN/wlan.8</code>, <code>src/WLAN/wland.8</code>, <code>build-userland.sh:763-776</code>, nextbsd/nextbsd#396 (the pane pattern this is the backend for), userland#47</p></section>
<section id="D9" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">D9 · CI: Bluetooth boot-test gates (BT-RPC-OK, BT-CLI-OK, BT-PREFS-OK, BT-NOSTACK→BT-NOADAPTER flip when the kernel bakes netgraph) <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd/issues/480">nextbsd#480</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#D1">D1</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/206">nextbsd-userland#206</a>)</td></tr></table>
<p>Parent: nextbsd/nextbsd#473. Notes: <code>e16/3-bluetoothd-cli.md</code> §8.</p>
<h2>Why</h2>
<p>There is no Bluetooth in qemu, so CI can only prove that bluetoothd boots, registers, answers a bounded RPC, persists, and does not disturb the wired boot. That is still the line between "wland-style silently unprobed" (<code>wedge-check.sh:153,156</code>; no <code>WLAN</code> expectation in <code>tests/boot-test.sh</code>) and a daemon whose liveness is asserted on every image. This ticket owns the <code>nextbsd/nextbsd</code> side of the gates that D1/D5/D6 emit from <code>run.sh</code>.</p>
<h2>Exact change</h2>
<p><code>tests/boot-test.sh</code> (expect blocks placed after <code>IPCFG-IPCONFIG-OK</code>, before <code>LAUNCHD-MACH-RUN-DONE</code>, in the style of <code>:986-997</code>):</p>
<ul>
<li><code>BT-RPC-OK</code> — FAIL if absent ("bluetoothd did not claim org.nextbsd.bluetooth")</li>
<li><code>BT-CLI-OK</code> — FAIL on <code>BT-CLI-FAIL</code> or timeout ("bluetooth status did not answer within 15s")</li>
<li><code>BT-PREFS-OK</code> — FAIL on <code>BT-PREFS-FAIL</code> (D5's round-trip test); WARN if absent on pre-D5 images</li>
<li><code>BT-NOSTACK</code> / <code>BT-NOADAPTER</code> — informational, but once <code>nextbsd-kernel</code> bakes <code>ng_btsocket</code> (K1) the expectation flips: <code>BT-NOSTACK</code> becomes FAIL ("kernel lost netgraph/Bluetooth — the wlan_xauth trap, see kernel#52")</li>
<li><code>WEDGE-CHECK</code> output must list <code>org.nextbsd.bluetooth</code> as <code>OK</code>, not <code>UNPROBED</code></li>
<li><code>DAEMON-STATE-OK</code> already covers the resident job</li>
</ul>
<p>Also: add <code>bluetooth</code> and <code>bluetoothd</code> to the <code>pkglist</code>/superseded audit if <code>hcsecd</code> is on the image (the image must not start it; D4). Document the markers in <code>tests/README</code> next to the IPCFG ones.</p>
<h2>Acceptance</h2>
<ul>
<li>[ ] amd64 and arm64 img/iso boot tests pass with the new expects on an image containing D1</li>
<li>[ ] Deleting the plist on a test image makes the run fail at <code>BT-RPC-OK</code> (negative test done once by hand, recorded in the PR)</li>
<li>[ ] After K1 lands, a kernel built without <code>ng_btsocket</code> fails CI at <code>BT-NOSTACK</code></li>
<li>[ ] Wired IPCFG markers unaffected; total boot-test time increases by < 20 s</li>
</ul>
<h2>Links</h2>
<p><code>tests/boot-test.sh:858-997</code> (ipconfigd gates), <code>ul/overlay/usr/tests/freebsd-launchd-mach/run.sh:1498-1520</code>, <code>wedge-check.sh</code>, <code>daemon-state.sh</code>, https://pkgdemon.github.io/nextbsd-wlan-plan.html §1.1 (the unbaked-module trap)</p></section>
<section id="K4" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">K4 · Contract: bluetoothd runs iwmbtfw/rtlbtfw on USB arrival for controllers that boot in bootloader/ROM mode (devd's iwmbtfw.conf/rtlbtfw.conf, without devd) <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/202">nextbsd-userland#202</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill info">Sequence</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#K3">K3</a> (<a href="https://github.com/nextbsd/nextbsd/issues/476">nextbsd#476</a>), <a href="#D2">D2</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/207">nextbsd-userland#207</a>)</td></tr></table>
<h2>Problem</h2>
<p>On stock FreeBSD two devd rule files fire the firmware loaders on USB attach: <code>usr.sbin/bluetooth/iwmbtfw/iwmbtfw.conf</code> (<code>system USB / subsystem DEVICE / type ATTACH / vendor 0x8087 / product (0x07dc|0x0a2a|0x0aa7|0x0a2b|0x0aaa|0x0025|0x0026|0x0029|0x0032|0x0033|0x0035|0x0036)</code> → <code>/usr/sbin/iwmbtfw -d $cdev -f …</code>) and <code>rtlbtfw.conf</code> (365 lines: generic <code>vendor 0x0bda</code> + <code>interface 0</code> + <code>intclass 0xe0/intsubclass 0x01/intprotocol 0x01</code>, plus ~40 explicit VID/PIDs for 8821CE/8851BE/8852AE/BE/CE/8922AE/8723AE/BE/BU/DE/8761BUV/8821AE/8822BE/CE → <code>/usr/sbin/rtlbtfw -d $cdev -f …</code>). Then the stock <code>sbin/devd/bluetooth.conf</code> runs <code>service bluetooth quietstart ubtN</code> when the re-enumerated device attaches as <code>ubt</code>.</p>
<p>NextBSD has no devd (stripped in nextbsd-freebsd-compat), launchd's <code>HardwareMatch</code> is iter-1 parse-only and matches <code>name</code>/<code>class</code>/<code>driver</code> — never VID/PID (<code>src/launchd/src/core.c:262-270, 6014-6047</code>), and the in-kernel IOCatalogue matches PCI and FDT only (<code>nextbsd-kernel</code> <code>src-overlay/sys/sys/iocatalogue.h:24-31</code>). So nothing loads Bluetooth firmware, and an Intel laptop's Bluetooth never appears.</p>
<p>This ticket fixes the <strong>contract</strong> so the daemon ticket (area 2's <code>bluetoothd</code> v0) implements it; it is Sequence, not Ship, because it lands with the daemon.</p>
<h2>Change</h2>
<p>In <code>bluetoothd</code> (or, if area 2 prefers, a tiny <code>org.nextbsd.btfw</code> helper it spawns), on USB device arrival (libIOKit <code>IOKitNotify</code>, the same registry subscription <code>diskarbitrationd</code> uses in <code>src/DiskArbitration/da_iokit_subscribe.c</code>):</p>
<ol>
<li>Match: VID <code>0x8087</code> with one of the twelve PIDs → <code>iwmbtfw</code>; VID <code>0x0bda</code> interface 0 class <code>e0/01/01</code>, or one of the <code>rtlbtfw.conf</code> VID/PIDs → <code>rtlbtfw</code>. Keep the id tables in one source file with a comment pointing at the two <code>.conf</code> files so they can be re-diffed on each FreeBSD import.</li>
<li>Run <code>/usr/sbin/{iwmbtfw,rtlbtfw} -d ugenX.Y -f /usr/share/firmware/bluetooth/{intel,rtl_bt}</code> (K3 paths) with a timeout; log stdout/stderr through ASL.</li>
<li>Expect the device to detach and re-attach; the <code>ubtN</code> arrival then goes through the normal graph-assembly path (<code>bluetooth_setup_stack()</code> equivalent). Do <strong>not</strong> attempt <code>mkpeer</code> on an Intel part before firmware is up — that is the hard-lock <code>ng_ubt_intel.c:33-37</code> warns about; the kernel guards it, the daemon must not route around it.</li>
<li>If the loader fails, publish the adapter as <code>firmware-failed</code> in the daemon's state (SCDynamicStore key per area 2) so the CLI can say why there is no adapter.</li>
</ol>
<p>Also handle the detach: on <code>ubtN</code> departure, <code>ngctl shutdown ubtNhci:</code> / <code>ubtNl2cap:</code> (what <code>service bluetooth quietstop</code> did).</p>
<h2>Acceptance</h2>
<ul>
<li>[ ] Id tables for Intel and Realtek exist in <code>bluetoothd</code> with a re-diff comment; unit test that every PID from the two upstream <code>.conf</code> files is present</li>
<li>[ ] On an Intel 8265/9560/AX200 laptop: plug/boot → loader runs → <code>ubt0</code> attaches → adapter shows up in <code>bluetooth status</code> (CLI from area 3) — recorded in the hardware matrix (K6)</li>
<li>[ ] On a Realtek 8761BU dongle: same</li>
<li>[ ] On a class-E0 CSR dongle: no loader runs; adapter appears directly</li>
<li>[ ] Loader failure is visible in the daemon's published state and ASL, and does not wedge the daemon</li>
<li>[ ] Detach tears the graph down; re-plug works without reboot</li>
</ul>
<h2>Related</h2>
<ul>
<li>nextbsd/nextbsd#412 (phase 2), #473</li>
<li>K3 (firmware files), K1 (kernel), D1 (bluetoothd v0 — area 2's id)</li>
<li>FreeBSD <code>usr.sbin/bluetooth/{iwmbtfw,rtlbtfw}/*.conf</code>, <code>sbin/devd/bluetooth.conf</code>, <code>libexec/rc/rc.d/bluetooth</code></li>
</ul></section>
<section id="D10" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">D10 · Bluetooth hardware bring-up run: first execution of bluetoothd scan/pair/reconnect on a real USB dongle (test matrix + findings) <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd/issues/481">nextbsd#481</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill info">Sequence</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code> <code>needs-hardware</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#D2">D2</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/207">nextbsd-userland#207</a>), <a href="#D3">D3</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/208">nextbsd-userland#208</a>), <a href="#D4">D4</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/209">nextbsd-userland#209</a>), <a href="#D8">D8</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/213">nextbsd-userland#213</a>)</td></tr></table>
<p>Parent: nextbsd/nextbsd#473. Notes: <code>e16/3-bluetoothd-cli.md</code> §3.3, §11, §12.</p>
<h2>Why</h2>
<p>Everything past <code>BT-NOADAPTER</code> is reasoned from source, never executed — the same honest state WLAN was in at userland#46 ("Everything past that needs real hardware"). Two things are genuinely unknown until a radio is plugged in: whether Secure Simple Pairing works through <code>ng_hci</code> at all (no FreeBSD base tool has ever sent <code>Write_Simple_Pairing_Mode</code>; <code>hccontrol</code> has no SSP command), and how the dongles we own report <code>Read_Local_Supported_Features</code>. This ticket is the first run and the record of what it found; it gates calling D2–D8 done.</p>
<h2>Exact change</h2>
<p>No code by default. A checklist executed on real hardware, results pasted into this issue, and follow-up tickets filed for every deviation:</p>
<ol>
<li>Dongle inventory: at least one CSR8510-class (BT 4.0, SSP) and, if available, one Intel/Realtek combo card that <code>ng_ubt</code> claims. Record <code>usbconfig</code> ids and <code>Read_Local_Supported_Features</code> bit 51 (SSP).</li>
<li><code>BT-ADAPTER-OK</code> within 5 s of plug-in; <code>ngctl list</code> graph matches D2's expectation; restart-adopts; unplug/replug cycle ×5.</li>
<li><code>bluetooth scan</code> finds a discoverable phone and a keyboard with names and (if <code>Write_Inquiry_Mode 1</code> accepted) RSSI.</li>
<li><code>bluetooth pair</code> numeric comparison with a phone; passkey entry with a keyboard; legacy PIN with any old device on hand. Note the controller's own confirmation timeout (spec default ~30 s, unverified) versus bluetoothd's 60 s.</li>
<li>Reboot; keyboard reconnects (<code>bluetooth list</code> → connected) with no user action; <code>Link_Key_Request</code> answered from the <code>.keys</code> file (log shows <code>key: exists</code>).</li>
<li><code>bluetooth unpair</code>; device must re-pair.</li>
<li><code>sdpd</code> child visible; <code>sdpcontrol browse</code> from a second machine.</li>
<li>Negative: start <code>hcsecd</code> by hand → <code>BT-SEC-CONFLICT</code>; unplug mid-pairing → clean <code>failed</code>, adapter usable after replug.</li>
</ol>
<h2>Acceptance</h2>
<ul>
<li>[ ] Each step above has a pasted transcript (log excerpt + CLI output) or a linked follow-up ticket explaining the failure</li>
<li>[ ] The plan page's hardware table is updated with the tested dongles (works / SSP yes-no / notes)</li>
<li>[ ] D2, D3, D4, D8 are closed only after this run, or their remaining gaps are re-filed as their own tickets</li>
</ul>
<h2>Links</h2>
<p>userland#46 "Testing" section, <code>e16/3-bluetoothd-cli.md</code> §3.3 table, <code>usr.sbin/bluetooth/hccontrol/*.c</code> (absence of SSP commands), FreeBSD Handbook Bluetooth chapter (legacy PIN pairing walkthrough)</p></section>
<h3>Stage 3 — keyboards, mice & trackpads (HID)</h3>
<section id="H2" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">H2 · bluetoothd: HID profile driver — generate bthidd.conf on pair, supervise bthidd -u, keyboards usable pre-login <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/214">nextbsd-userland#214</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>), <a href="#D4">D4</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/209">nextbsd-userland#209</a>), <a href="#D5">D5</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/210">nextbsd-userland#210</a>), <a href="#D7">D7</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/212">nextbsd-userland#212</a>)</td></tr></table>
<h2>Why</h2>
<p>FreeBSD's <code>bthidd(8)</code> is the Classic-HID engine we supervise (agreed shape: bluetoothd supervises stock daemons). It has no control socket and a static config: devices not listed in <code>/etc/bluetooth/bthidd.conf</code> are <strong>rejected</strong> when they connect (<code>server.c:244-250</code>), the file is read once, and SIGHUP is a shutdown, not a reload (<code>bthidd.c:138-140,249-253</code>; main loop <code>bthidd.c:167</code>). So bluetoothd must own the config file's contents and bthidd's lifecycle, and must have both bthidd and hcsecd listening before a user touches a paired keyboard at the login window.</p>
<p>Reconnect model to encode (<code>client.c:63-118</code>): after pairing the <strong>host</strong> initiates the first connection (device flagged <code>new_device</code> in <code>/var/db/bthidd.hids</code>); once a session has been established the flag is cleared (<code>client.c:179</code>, <code>server.c:255-256</code>) and, for devices advertising <code>HIDReconnectInitiate</code>, bthidd only listens on PSM 0x11/0x13 (<code>server.c:96-138</code>) for device-initiated reconnects. The device's reconnect triggers an HCI <code>Link_Key_Request</code> that hcsecd answers (<code>hcsecd.8</code>).</p>
<h2>Change</h2>
<p>Add an HID driver to <code>bluetoothd</code> (<code>src/Bluetooth/</code>, beside the wland-shaped core):</p>
<ol>
<li><strong>Pair hook.</strong> When area D's pairing completes for a device whose SDP record has the HID service (UUID <code>0x1124</code>), fetch the HID attributes the way <code>bthidcontrol Query</code> does (<code>bthidcontrol/sdp.c:58-80</code>: ProtocolDescriptorList, AdditionalProtocolDescriptorLists, <code>0x0205</code> ReconnectInitiate, <code>0x0206</code> HIDDescriptorList, <code>0x0209</code> BatteryPower, <code>0x020d</code> NormallyConnectable, DeviceID vendor/product/version). Either exec <code>/usr/sbin/bthidcontrol -a <bdaddr> Query</code> and capture the stanza, or link the same logic. Store the result in the paired-device record (SCPreferences, area D) so <code>bthidd.conf</code> is <strong>derived</strong> state.</li>
<li><strong>Config generation.</strong> Regenerate a bluetoothd-owned <code>bthidd.conf</code> (pass with <code>-c</code>) from the paired-device records at start and on every change; keep <code>/var/db/bthidd.hids</code> (<code>-H</code>) as bthidd's own; on pair make sure the device is <em>absent</em> from the hids file so the first connect is host-initiated.</li>
<li><strong>Supervision.</strong> Run <code>bthidd -d -c <conf> -H <hids> -p <pid> -u -a <adapter bdaddr></code> as a child once the adapter's HCI node is up and hcsecd is running; restart it on config change (log that this drops other HID sessions until H3 lands); <code>-t</code> may be lowered from 10 s for snappier first connects.</li>
<li><strong>Unpair.</strong> Remove the record, regenerate conf, <code>bthidcontrol Forget</code> (or drop the hids line), restart bthidd; area D drops the link key.</li>
<li><strong>State.</strong> Publish <code>State:/Bluetooth/Device/<addr></code> <code>Profiles=[HID]</code> and <code>Connected</code> — bthidd exposes no status; watch its syslog (<code>"Opening outbound session"</code>, <code>"Rejecting"</code>, <code>"Could not open /dev/vkbdctl"</code>) and the hids-file mtime as the v0 signal, and surface <code>Could not open /dev/vkbdctl</code> / <code>/dev/uinput</code> / <code>/dev/consolectl</code> as a <code>bluetooth status</code> error (they are otherwise silent failures).</li>
<li><strong>Always <code>-u</code>.</strong> Both sinks are always fed by bthidd (vkbd/consolectl unconditionally; uinput gated by <code>kern.evdev.rcpt_mask</code>, <code>btuinput.c:474-484,511-519</code>), so <code>-u</code> is safe under every mask value and is required for per-device evdev nodes (H4/H5).</li>
<li><strong>CLI.</strong> <code>bluetooth status</code> shows HID devices with keyboard/mouse flags; <code>bluetooth pair</code> prints a clear "LE-only HID (HOGP) is not supported yet" when the inquiry result carries no BR/EDR HID service (see H7).</li>
</ol>
<p>Not in scope: the X-side visibility of uinput nodes (H4/H5); trackpads (H6); LE (H7).</p>
<h2>Acceptance</h2>
<ul>
<li>[ ] <code>bluetooth pair <kbd></code> on real hardware produces a stanza equivalent to <code>bthidcontrol -a <addr> Query</code>, restarts bthidd, and the keyboard types in the text console within <code>-t</code> seconds (host-initiated first connect).</li>
<li>[ ] After reboot with nothing touched, pressing a key on the paired keyboard reconnects it (device-initiated) and it types at the console <strong>and</strong> at the Gershwin login window (with the H4-decided <code>rcpt_mask</code>).</li>
<li>[ ] <code>bluetooth unpair <kbd></code> removes the stanza and hids entry; the device is rejected on its next connect attempt (bthidd log line) and <code>bluetooth status</code> no longer lists it.</li>
<li>[ ] Ordering: <code>launchctl list</code> shows <code>org.nextbsd.bluetoothd</code> running before the loginwindow job starts X; bthidd and hcsecd are children and are restarted by bluetoothd if they die.</li>
<li>[ ] <code>bthidd.conf</code> is regenerated from SCPreferences at boot (delete it, reboot, it is back).</li>
<li>[ ] Failure to open <code>/dev/vkbdctl</code> (e.g. kernel without H1) is reported by <code>bluetooth status</code>, not just syslog.</li>
</ul>
<h2>Links</h2>
<ul>
<li>Epic nextbsd/nextbsd#473; area-4 notes <code>e16/4-hid.md</code> §4-5</li>
<li><code>usr.sbin/bluetooth/bthidd/{bthidd.c,client.c,server.c,session.c,btuinput.c}</code>, <code>bthidcontrol/sdp.c</code>, <code>libexec/rc/rc.d/bthidd</code></li>
<li>WLAN template: <code>org.nextbsd.wland</code> supervising <code>wpa_supplicant</code></li>
</ul>
<p><strong>Note (coordination):</strong> D4 replaces <code>hcsecd</code>; wherever this ticket says hcsecd answers <code>Link_Key_Request</code>, bluetoothd's security manager (D4) does. bthidd is supervised through D7's child-supervision hook.</p></section>
<section id="H3" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">H3 · bthidd: reload config on SIGHUP without dropping sessions; rescan all devices per tick (NextBSD patch, upstream candidate) <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/215">nextbsd-userland#215</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>S</td><th>Track</th><td><span class="pill info">Harden</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#H2">H2</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/214">nextbsd-userland#214</a>)</td></tr></table>
<h2>Why</h2>
<p>With H2, every pair/unpair restarts <code>bthidd</code>, and a restart disconnects every connected Bluetooth keyboard and mouse for the restart plus reconnect window (users lose their keyboard while pairing a mouse). Root causes in releng/15.1:</p>
<ul>
<li><code>bthidd.c:138-140</code> installs the same handler for SIGTERM/SIGHUP/SIGINT; the handler only increments <code>done</code> (<code>bthidd.c:249-253</code>) and the main loop <code>for (done = 0; !done; )</code> (<code>bthidd.c:167</code>) exits. There is no reload path; <code>read_config_file()</code>/<code>clean_config()</code> exist (<code>bthid_config.h:59-60</code>) but are only called at start.</li>
<li><code>client_rescan()</code> inspects <strong>one</strong> configured device per <code>-t</code> interval (<code>client.c:73</code>, <code>get_next_hid_device(d)</code> advances a static cursor), so with N devices the first outbound connect for the last one can take N x 10 s.</li>
<li>There is no status interface at all; the only observable state is syslog and <code>/var/db/bthidd.hids</code> writes.</li>
</ul>
<h2>Change</h2>
<p>Carry a patch to <code>usr.sbin/bluetooth/bthidd</code> in the NextBSD userland build (and send it upstream):</p>
<ol>
<li>SIGHUP → set a <code>reload</code> flag; in the main loop, re-read the config into a new list, diff by bdaddr: keep sessions for devices still present (update descriptor/flags in place), close sessions for removed devices, mark added devices <code>new_device</code> so the host initiates. Keep SIGTERM/SIGINT as shutdown.</li>
<li><code>client_rescan()</code>: iterate the whole list per tick (respecting <code>connect_in_progress</code>), or at least start the cursor at the first device without a session.</li>
<li>Optional: dump session state (bdaddr, keyboard/mouse, uinput node names) to a file or on SIGUSR1 so bluetoothd can publish <code>Connected</code> without parsing syslog.</li>
<li>bluetoothd (H2) then sends SIGHUP instead of restarting when the patched bthidd is detected (e.g. <code>bthidd -h</code> mentions reload, or a version string).</li>
</ol>
<h2>Acceptance</h2>
<ul>
<li>[ ] With keyboard A connected, pairing mouse B (which appends a stanza and SIGHUPs bthidd) does <strong>not</strong> disconnect A (no vkbd close/reopen; <code>xinput</code>/console keeps working); B connects within one rescan tick.</li>
<li>[ ] Removing a stanza and SIGHUP closes only that device's session.</li>
<li>[ ] SIGTERM still terminates cleanly (pid file removed).</li>
<li>[ ] Patch applies to releng/15.1 <code>usr.sbin/bluetooth/bthidd</code> and is filed as a FreeBSD review/PR (link in this issue).</li>
</ul>
<h2>Links</h2>
<ul>
<li>Epic nextbsd/nextbsd#473; <code>e16/4-hid.md</code> §4</li>
<li><code>usr.sbin/bluetooth/bthidd/{bthidd.c,client.c,bthid_config.h,parser.y}</code></li>
</ul></section>
<section id="H5" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">H5 · Bluetooth mice and trackpads in X via per-device uinput nodes (blocked on input hotplug) <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd/issues/483">nextbsd#483</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill info">Sequence</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code> <code>area:desktop</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#H2">H2</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/214">nextbsd-userland#214</a>), <a href="#H4">H4</a> (<a href="https://github.com/nextbsd/nextbsd/issues/482">nextbsd#482</a>)</td></tr></table>
<h2>Why</h2>
<p>Keyboards have a hotplug-free path into X (vkbd → kbdmux aggregate evdev, H4). Mice mostly do not: the aggregate "System mouse" route duplicates <code>psm(4)</code> events on laptops and can never carry multitouch, so the real path is <code>bthidd -u</code>'s per-device uinput node ("Bluetooth Mouse", <code>btuinput.c:339-370</code>, <code>UNIQ</code>=bdaddr) — which appears at connect time and is invisible to a running XLibre until the input epic delivers a hotplug interface (H4 Q2).</p>
<h2>Change (once H4 is answered)</h2>
<ol>
<li>If a devd-protocol relay or IOKit-backed libudev-devd exists: verify that creating the uinput node after X is up results in libinput adding the device (<code>xinput list</code> shows "Bluetooth Mouse" with the bdaddr as <code>Device Node</code>/uniq), that removal on disconnect (<code>session_close</code>, <code>session.c:223-230</code>) removes it, and that reconnects do not accumulate stale devices.</li>
<li>If the decision is "aggregate policy": document that BT mice work through "System mouse" (rcpt_mask bit 0), verify no duplicate motion on a <code>psm(4)</code> laptop with the chosen mask, and record that BT trackpad multitouch is therefore out of reach (H6 parked harder).</li>
<li>Either way: add an <code>InputClass</code> snippet shipped with the desktop overlay if libinput needs hints for bthidd's devices (e.g. <code>MatchProduct "Bluetooth Mouse"</code> for scroll method / natural scrolling defaults), and check that <code>INPUT_PROP_POINTER</code> (set at <code>btuinput.c:357</code>) classifies them as pointers, not touchscreens.</li>
<li>Interim, if hotplug is far off: evaluate having bluetoothd trigger an X-side rescan; note there is <strong>no</strong> "rescan inputs" request in the X server — this is why the interface must be at the libudev-devd level.</li>
</ol>
<h2>Acceptance</h2>
<ul>
<li>[ ] Pair a BT mouse while Gershwin is running; the pointer moves within the reconnect window without restarting X.</li>
<li>[ ] Turn the mouse off and on: exactly one "Bluetooth Mouse" in <code>xinput list</code> afterwards (no stale entries).</li>
<li>[ ] Wheel and horizontal wheel work when the descriptor has them (<code>has_wheel</code>/<code>has_hwheel</code>, <code>btuinput.c:355-356</code>).</li>
<li>[ ] Reboot with the mouse paired: it works at the login window after the first click/motion.</li>
<li>[ ] On a <code>psm(4)</code> laptop with the H4 mask: no duplicate pointer motion from the internal device.</li>
</ul>
<h2>Links</h2>
<ul>
<li>Epic nextbsd/nextbsd#473; <code>e16/4-hid.md</code> §3, §5</li>
<li>H4 for the decision; the input-management epic for delivery</li>
</ul></section>
<h3>Stage 4 — audio</h3>
<section id="A4" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">A4 · bluetoothd: A2DP source — on connect of an AudioSink device, run/retarget virtual_oss at `/dev/bluetooth/<addr>`, publish the node, fall back on disconnect <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/218">nextbsd-userland#218</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>L</td><th>Track</th><td><span class="pill ok">Ship</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>), <a href="#A2">A2</a> (<a href="https://github.com/nextbsd/nextbsd/issues/485">nextbsd#485</a>), <a href="#A3">A3</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/236">nextbsd-kernel#236</a>), <a href="#D1">D1</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/206">nextbsd-userland#206</a>), <a href="#D8">D8</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/213">nextbsd-userland#213</a>)</td></tr></table>
<h2>Why</h2>
<p>This is the profile users notice: music/video out of a Bluetooth headset or speaker. With A1-A3 the whole protocol path exists in base (<code>virtual_oss</code> + <code>voss_bt.so</code>: SDP lookup of the AVDTP PSM, two L2CAP <code>SOCK_SEQPACKET</code> sockets, AVDTP signalling, SBC encode — <code>lib/virtual_oss/bt/bt.c</code>, <code>avdtp.c</code>). What is missing is the orchestrator: something that knows a paired device just connected, knows from SDP that it is an <code>AUDIO_SINK</code> (0x110B), starts or retargets the mixer, tells the system where the new output is, and undoes all of it when the link drops. That is <code>bluetoothd</code>'s job, exactly as <code>wland</code> owns <code>wpa_supplicant</code> (<code>src/WLAN/wland.c:262-275</code> fork/exec, <code>:356</code>/<code>:586</code> reaping).</p>
<p>General audio-device management (which output is default, volume, a CoreAudio-shaped layer) is <strong>out of scope</strong> — it is the future audio epic. This ticket defines the seam and ships an interim that works without it.</p>
<h2>Exact change</h2>
<ol>
<li>Profile detection: after ACL up + SDP browse (D track), classify <code>AUDIO_SINK</code> / <code>AUDIO_SOURCE</code> records and store <code>Profiles</code> on the device object.</li>
<li>Two modes, chosen at runtime:
- <strong>Cooperative</strong> (audio epic present, detected by <code>/dev/dsp.ctl</code> existing and belonging to the system virtual_oss): issue the switch through the audio epic's API; interim shim = exec <code>virtual_oss_cmd /dev/dsp.ctl -P /dev/bluetooth/<addr></code> (and <code>-R</code> if the device is also an <code>AUDIO_SOURCE</code>), remembering the previous <code>-P</code> target from <code>VIRTUAL_OSS_GET_SYSTEM_INFO</code> (<code>ctl.c:586-592</code>) for the fallback. <code>main.c:2205-2216</code> re-parses these options live and calls <code>voss_tx_backend_refresh()</code>, so clients holding <code>/dev/dsp</code> keep playing.
- <strong>Standalone</strong> (no system mixer): fork/exec <code>/usr/sbin/virtual_oss -S -C 2 -c 2 -r 48000 -b 16 -s 8ms -R /dev/null -P /dev/bluetooth/<addr> -d dsp.bt<N> -t dsp.bt<N>.ctl</code> as a supervised child (SIGCHLD/waitpid like wland; restart with backoff while the ACL is up; kill on disconnect, unpair, or adapter loss). Not a per-device launchd job: the child's lifetime is the link's and launchd has no ordering to express that.</li>
<li>Publish <code>State:/Bluetooth/Device/<addr>/Audio = { Node: "/dev/dsp.bt0" | "/dev/dsp", Role: source|sink, Codec: SBC, Active: bool }</code> in SCDynamicStore; clear on disconnect. <code>bluetooth status</code> shows it; <code>bluetooth audio <addr> [on|off]</code> toggles it.</li>
<li>Policy knob in SCPreferences (<code>AutoSwitchAudio</code>, default true) so a user can keep BT audio manual.</li>
<li>Man page section in <code>bluetoothd.8</code> describing the two modes and the SC keys — this is the contract the audio epic implements against.</li>
</ol>
<h2>Acceptance criteria</h2>
<ul>
<li>[ ] With a real dongle and a paired A2DP headset: connect -> <code>/dev/dsp.bt0</code> appears within 3 s, <code>cat music.wav > /dev/dsp.bt0</code> plays on the headset; walk out of range -> child reaped, SC key cleared, no zombie <code>virtual_oss</code>; walk back -> re-established without user action</li>
<li>[ ] Cooperative mode against a manually started <code>virtual_oss ... -d dsp -t dsp.ctl</code>: connect switches playback to the headset without interrupting an <code>aplay</code>/<code>mpv</code> already holding <code>/dev/dsp</code>; disconnect restores the previous device</li>
<li>[ ] Boot-test (no radio): bluetoothd's audio state machine unit test drives connect/disconnect against a stub that makes <code>/dev/bluetooth/<addr></code> fail at SDP; asserts the child is spawned, exits non-zero, is retried with backoff, and is torn down on disconnect with the SC key never left set</li>
<li>[ ] <code>bluetoothd.8</code> documents <code>State:/Bluetooth/Device/<addr>/Audio</code> and the <code>AutoSwitchAudio</code> preference</li>
</ul>
<h2>Links</h2>
<ul>
<li>Epic nextbsd/nextbsd#473 · seed #412 · depends on daemon v0 (D track) and baked BT nodes (K track) — IDs assumed, reconcile when filed</li>
<li><code>usr.sbin/virtual_oss/virtual_oss/{main.c,ctl.c}</code>, <code>virtual_oss_cmd.8:67-97</code>, <code>lib/virtual_oss/bt/bt.c</code> (releng/15.1)</li>
<li>Research: <code>e16/5-audio.md</code> sections 1.3, 4, 5, 6</li>
</ul></section>
<section id="A5" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">A5 · bluetoothd: A2DP sink — supervise virtual_bt_speaker so a phone can play through the machine's speakers <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/219">nextbsd-userland#219</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill info">Sequence</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>), <a href="#A3">A3</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/236">nextbsd-kernel#236</a>), <a href="#D1">D1</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/206">nextbsd-userland#206</a>)</td></tr></table>
<h2>Why</h2>
<p>The reverse direction already exists in base: <code>virtual_bt_speaker(8)</code> (<code>usr.sbin/virtual_oss/virtual_bt_speaker</code>, built under <code>MK_BLUETOOTH</code>) registers an <code>AUDIO_SINK</code> SDP record through <code>sdpd</code> (<code>bt_speaker.c:80-91</code>, <code>sdp_open_local</code> + <code>sdp_register_service</code>), listens on the AVDTP PSM (<code>:113-127</code>), answers AVDTP as the acceptor (<code>avdtp.c:191, 589</code>), decodes SBC (<code>sbc_encode.c:417, 629</code>) and writes to an OSS device (<code>-d /dev/dspX</code>). It is a one-process profile; it only needs someone to start it after <code>sdpd</code> is up and to stop it when the adapter goes away. Lower priority than A4 (phones already have speakers) but nearly free.</p>
<p>Note: it does <strong>not</strong> need <code>voss_bt.so</code> (it links <code>libbluetooth</code>/<code>libsdp</code> directly, <code>virtual_bt_speaker/Makefile</code>), but it does need a running local SDP server — whichever of <code>sdpd</code> / bluetoothd-owned SDP the D track lands.</p>
<h2>Exact change</h2>
<ul>
<li>bluetoothd starts <code>/usr/sbin/virtual_bt_speaker -d /dev/dsp</code> (foreground, no <code>-B</code>) as a supervised child when an adapter is up <strong>and</strong> the <code>A2DPSink</code> preference is enabled (SCPreferences, default off — it advertises the machine as a speaker to everything nearby); passes <code>-p <sdpd socket></code> if bluetoothd relocates the SDP control socket.</li>
<li>Publish <code>State:/Bluetooth/Adapter/<name>/A2DPSink = { Running: bool, Peer: <addr>|absent }</code>; <code>bluetooth status</code> shows it.</li>
<li>Stop on adapter detach / preference off; restart with backoff on crash.</li>
<li>Output device: <code>/dev/dsp</code> today; when the audio epic lands this becomes its default-output value (interface: bluetoothd reads it, never picks).</li>
</ul>
<h2>Acceptance criteria</h2>
<ul>
<li>[ ] With a dongle: enable <code>A2DPSink</code>, pair a phone, play music on the phone -> audio out of the HDA/USB device; disconnect -> child stays listening; disable preference -> child gone and SDP record unregistered</li>
<li>[ ] Boot-test (no radio): with the preference on and no adapter, nothing is spawned; with a fake adapter-up event and no sdpd, the child fails, is retried with backoff, and the SC key stays <code>Running: false</code></li>
<li>[ ] Documented in <code>bluetoothd.8</code> and <code>bluetooth.8</code></li>
</ul>
<h2>Links</h2>
<ul>
<li>Epic nextbsd/nextbsd#473 · A4 · D track (sdpd ownership)</li>
<li><code>usr.sbin/virtual_oss/virtual_bt_speaker/Makefile</code>, <code>lib/virtual_oss/bt/bt_speaker.c</code> (upstream <code>backend_bt/bt_speaker.c</code>), <code>virtual_bt_speaker.8</code></li>
<li>Research: <code>e16/5-audio.md</code> section 1.3</li>
</ul></section>
<section id="A7" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">A7 · bluetoothd: AVRCP target — accept the headset's play/pause/next/volume keys and deliver them to the session <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/220">nextbsd-userland#220</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>L</td><th>Track</th><td><span class="pill info">Sequence</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#A4">A4</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/218">nextbsd-userland#218</a>), <a href="#D1">D1</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/206">nextbsd-userland#206</a>)</td></tr></table>
<h2>Why</h2>
<p>No AVRCP exists anywhere in FreeBSD (<code>virtual_oss</code> has none — <code>grep -ri avrcp</code> over <code>freebsd/virtual_oss</code> and <code>lib/virtual_oss/bt</code> is empty; ports: only wireshark's dissector list). So with A4 a headset's buttons do nothing and its volume rocker cannot reach the mixer. Every consumer headset expects the PC to be an AVRCP <strong>target</strong> (TG) with at least PASSTHROUGH and, on 1.4+, absolute volume. This is userland-only: AVCTP over L2CAP PSM 0x0017, no kernel change.</p>
<h2>Exact change</h2>
<ol>
<li>bluetoothd listens on L2CAP PSM 0x0017 (<code>SOCK_SEQPACKET</code>, like <code>bt_speaker.c:113-127</code>); on a connection from a device with an active A2DP link, run a minimal AVRCP TG: answer <code>UNIT INFO</code>/<code>SUBUNIT INFO</code>, decode PASSTHROUGH (<code>PLAY</code>, <code>PAUSE</code>, <code>STOP</code>, <code>FORWARD</code>, <code>BACKWARD</code>, <code>VOLUME_UP</code>, <code>VOLUME_DOWN</code>), and <code>SetAbsoluteVolume</code> (AVRCP 1.4, vendor-dependent PDU 0x50). Reject everything else politely (NOT IMPLEMENTED) so metadata-hungry headsets don't drop the link.</li>
<li>Local SDP record <code>AV_REMOTE_CONTROL_TARGET</code> (0x110C): <code>sdpd</code> cannot register it (fixed profile list, <code>usr.sbin/bluetooth/sdpd/profile.c:51-76</code>) — add a profile to sdpd (small, copy <code>audio_sink.c</code>) or have bluetoothd's SDP server (D track) carry it. Pick whichever the D track chose.</li>
<li>Delivery: post <code>notify(3)</code> names <code>org.nextbsd.bluetooth.avrcp.<key></code> and publish <code>State:/Bluetooth/Device/<addr>/Audio/Volume</code> (0-127). Gershwin/X consumer (media-key injection) is a sibling ticket in the Gershwin repos, out of scope here. Absolute volume -> the audio epic's <code>SetVolume</code> on the device node (interim: <code>mixer -f /dev/dsp.bt0.ctl</code>-shaped no-op with a log line).</li>
</ol>
<h2>Acceptance criteria</h2>
<ul>
<li>[ ] With a dongle and an AVRCP-capable headset: pressing play/pause posts the notify name (observed with the <code>notifypoke</code>-style test tool in <code>tests/</code>); volume rocker updates the SC key</li>
<li>[ ] Boot-test (no radio): AVCTP frame parser unit-tested against captured PASSTHROUGH and SetAbsoluteVolume frames (hex fixtures in <code>tests/</code>); malformed frames are rejected without crashing bluetoothd</li>
<li>[ ] Headsets that probe for metadata (<code>GetCapabilities</code>, <code>RegisterNotification</code>) keep their A2DP stream up for 10 min</li>
<li>[ ] SDP record visible from another host (<code>sdpcontrol -a <us> browse</code> lists AV Remote Control Target)</li>
</ul>
<h2>Links</h2>
<ul>
<li>Epic nextbsd/nextbsd#473 · A4 · D track (SDP ownership)</li>
<li>AVRCP 1.6 spec sections 4.x (PASSTHROUGH), 6.13 (SetAbsoluteVolume); <code>lib/virtual_oss/bt/bt_speaker.c</code> for the L2CAP listener shape</li>
<li>Research: <code>e16/5-audio.md</code> section 3</li>
</ul></section>
<h3>Stage 5 — Bluetooth LE</h3>
<section id="B5" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">B5 · ng_hci/ng_l2cap LE hardening: honour LE_Read_Buffer_Size for LE ACL flow control, forward LE connection-parameter updates to the controller, implement the stub LE meta handlers <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-kernel/issues/234">nextbsd-kernel#234</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-kernel</code></td><th>Size</th><td>M</td><th>Track</th><td><span class="pill info">Harden</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>bug</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#B4">B4</a> (<a href="https://github.com/nextbsd/nextbsd/issues/478">nextbsd#478</a>), <a href="#K1">K1</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a>)</td></tr></table>
<h2>Why</h2>
<p>NextBSD compiles the Bluetooth nodes into the kernel, so any LE-path defect is a boot-visible failure rather than a module you can unload. Reading <code>releng/15.1</code>, the LE code has four known soft spots, none of which block a HOGP mouse but all of which bite under load or with picky peripherals:</p>
<ol>
<li><strong>LE buffer accounting.</strong> <code>LE_Read_Buffer_Size</code> is in the "no post processing" list (<code>sys/netgraph/bluetooth/hci/ng_hci_cmds.c:824</code>); the unit's ACL packet budget comes only from the BR/EDR <code>Read_Buffer_Size</code> reply (<code>ng_hci_main.c</code> <code>NG_HCI_BUFF_ACL_TOTAL</code>). Controllers with a separate, smaller LE pool (B4 measures this) can be over-driven, and <code>Number_Of_Completed_Packets</code> accounting then drifts.</li>
<li><strong>LE signalling parameter update.</strong> <code>ng_l2cap_process_cmd_urq</code> always replies ACCEPT (<code>ng_l2cap_evnt.c:363</code>) but the request is never turned into <code>LE_Connection_Update</code> (<code>ng_l2cap_cmds.c:224-226</code>, <code>/*TBD.*/</code>). Mice asking for a 7.5 ms interval stay at the connect-time interval; some peripherals disconnect when their accepted parameters never take effect.</li>
<li><strong>Stub LE meta handlers.</strong> <code>LE_Connection_Update_Complete</code> body is <code>/*TBD*/</code> (<code>ng_hci_evnt.c:571-578</code>); <code>LE_Read_Remote_Features_Complete</code> and <code>LE_Long_Term_Key_Request</code> fall through to free (<code>:602-606</code>). The LTK request is still mirrored to the raw hook so userland can answer, but the kernel connection descriptor never learns the encryption outcome on the peripheral-role path except via the generic <code>Encryption_Change</code> event - verify that path in B4.</li>
<li><strong><code>LE_Enhanced_Connection_Complete</code> (0x0a)</strong> is defined but unhandled: if userland enables it in <code>LE_Set_Event_Mask</code>, LE connections never register in the kernel. Either handle it (map to the same code as 0x01, keeping local/peer RPAs) or document that bit as forbidden.</li>
</ol>
<p>Also worth a look while in there: <code>ng_l2cap_con_wakeup</code> <code>panic()</code>s on an unknown pending command code (<code>ng_l2cap_cmds.c:228-232</code>) - should be an error, not a panic, once LE commands are added.</p>
<h2>Exact change</h2>
<ul>
<li><code>ng_hci_cmds.c</code>: post-process <code>LE_Read_Buffer_Size</code> (v1 and v2): if <code>hc_total_num_le_data_packets != 0</code>, keep a separate <code>le_pkts</code>/<code>le_size</code> budget in <code>ng_hci_unit_buff_t</code> (<code>ng_hci_var.h:62-75</code>) and have <code>ng_hci_send_data</code> / <code>Number_Of_Completed_Packets</code> charge LE connection handles against it; expose via <code>NGM_HCI_NODE_GET_BUFFER</code>.</li>
<li><code>ng_l2cap</code>: on <code>Connection_Parameter_Update_Request</code>, after ACCEPT, issue <code>LP_*</code>-style request to <code>ng_hci</code> that sends <code>LE_Connection_Update</code> (OCF 0x13, <code>ng_hci.h:1719-1728</code>) with the peer's parameters; handle <code>LE_Connection_Update_Complete</code> to update the connection descriptor.</li>
<li><code>ng_hci_evnt.c</code>: implement <code>LE_Read_Remote_Features_Complete</code> (store in con), <code>LE_Enhanced_Connection_Complete</code> (as 0x01), and leave <code>LE_Long_Term_Key_Request</code> to userland but comment it as such.</li>
<li>Replace the <code>panic()</code> default in <code>ng_l2cap_con_wakeup</code> with <code>NG_L2CAP_ERR</code> + free.</li>
<li>Upstream: send as a Phabricator review to FreeBSD (<code>takawata@</code>, <code>hselasky@</code> as reviewers); carry as a NextBSD patch until merged.</li>
</ul>
<h2>Acceptance criteria</h2>
<ul>
<li>[ ] With an Intel AX2xx controller reporting a separate LE pool, 1 h of HOGP mouse + notifications shows no <code>ng_hci</code> "could not send" / stall and <code>NGM_HCI_NODE_GET_BUFFER</code> counters return to baseline when idle</li>
<li>[ ] An MX Master 3S's connection-parameter-update request results in an <code>LE_Connection_Update_Complete</code> with the requested interval (btsnoop attached)</li>
<li>[ ] Enabling subevent 0x0a in the LE event mask no longer breaks connection registration</li>
<li>[ ] No <code>panic()</code> reachable from <code>ng_l2cap_con_wakeup</code> with an unknown command code</li>
<li>[ ] Patch series posted to reviews.freebsd.org and linked here</li>
</ul>
<h2>Links</h2>
<ul>
<li>Research note §1.2 ("What is missing")</li>
<li>FreeBSD LE commits: <code>fbc48c2bfb</code>, <code>3a601a2381</code>, <code>b32073c458</code></li>
</ul></section>
<section id="B6" style="background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:1rem 1.25rem;margin:1rem 0">
<h4 style="margin-top:0">B6 · bluetoothd LE engine: GAP scan/connect, ATT/GATT client, SMP pairing agent and LTK responder over the kernel's ATT/SMP sockets <span class="pill ok">Filed <a href="https://github.com/nextbsd/nextbsd-userland/issues/205">nextbsd-userland#205</a></span></h4>
<table class="compact"><tr><th>Repo</th><td><code>nextbsd/nextbsd-userland</code></td><th>Size</th><td>XL</td><th>Track</th><td><span class="pill info">Sequence</span></td></tr>
<tr><th>Labels</th><td colspan="5"><code>enhancement</code> <code>area:bluetooth</code></td></tr><tr><th>Depends on</th><td colspan="5"><a href="#B2">B2</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/204">nextbsd-userland#204</a>), <a href="#D4">D4</a> (<a href="https://github.com/nextbsd/nextbsd-userland/issues/209">nextbsd-userland#209</a>), <a href="#B4">B4</a> (<a href="https://github.com/nextbsd/nextbsd/issues/478">nextbsd#478</a>), <a href="#B5">B5</a> (<a href="https://github.com/nextbsd/nextbsd-kernel/issues/234">nextbsd-kernel#234</a>)</td></tr></table>
<h2>Why</h2>
<p>Every third-party keyboard and mouse a user is likely to bring (Logitech MX, Microsoft Surface, Keychron, most gaming mice) is LE-only HOGP; Classic (B3) covers headsets and Apple's Magic peripherals but none of those. The kernel already provides LE connections and the ATT/SMP fixed channels as sockets; the entire gap is this userland host. This ticket is the second engine behind the B2 interface - the policy layer, CLI, MIG surface and bond store do not change.</p>
<p>Deliberately <strong>not</strong> a port of NimBLE/Zephyr/BTstack: those need the raw ACL stream, which on netgraph means taking <code>ng_hci</code>'s single <code>acl</code> hook away from <code>ng_l2cap</code> and losing Classic (see B7 for the priced alternative). This engine is the <code>takawata/FreeBSD-BLE</code> shape - clean-room, or derived from it if the licence request from B4 succeeds.</p>
<h2>Exact change</h2>