Repository navigation
Expand file tree
/
Copy pathnextbsd-bluetooth-plan.html
More file actions
2120 lines (2105 loc) · 220 KB
/
Copy pathnextbsd-bluetooth-plan.html
File metadata and controls
2120 lines (2105 loc) · 220 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>NextBSD Bluetooth plan — bluetoothd, pairing, HID and audio (E16)</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="#decided">Decided</a><a href="#index">Index</a><a href="#area1">Kernel</a><a href="#area2">Engine/BLE</a><a href="#area3">bluetoothd</a><a href="#area4">HID</a><a href="#area5">Audio</a><a href="nextbsd-e16-tickets.html">Tickets</a></nav>
<p style="font-size:.9rem;margin:0 0 1rem"><a href="nextbsd-research.html">← NextBSD Research</a></p>
<h1>NextBSD Bluetooth — <code>bluetoothd</code>, pairing, HID and audio <span class="pill info">Research · epic plan</span></h1>
<p class="subtitle"><strong>The plan for EPIC E16 (<a href="https://github.com/nextbsd/nextbsd/issues/473">nextbsd#473</a>): 38 tickets in six stages, from five parallel deep dives</strong> covering the kernel and hardware, the engine and Classic-vs-BLE decision, the daemon and CLI, HID, and audio. Seed ticket and decision record: <a href="https://github.com/nextbsd/nextbsd/issues/412">nextbsd#412</a>. Background: <a href="freebsd-bluetooth-management.html">Apple stack research</a>. Template: <a href="nextbsd-wlan-plan.html">WLAN plan</a>. Every ticket in full: <a href="nextbsd-e16-tickets.html">E16 ticket drafts</a>.</p>
<section id="tldr" class="tldr"><h3>TL;DR</h3><ul>
<li><strong>There is no Darwin source to port</strong>, so E16 follows the WLAN pattern: a stock engine underneath, and our own <code>bluetoothd</code> (job <code>org.nextbsd.bluetoothd</code>, service <code>org.nextbsd.bluetooth</code>) plus a <code>bluetooth</code> CLI giving it a Mach face.</li>
<li><strong>The research page was wrong about LE.</strong> FreeBSD 15.1’s kernel already has LE HCI commands and events, LE connections in both roles, and the ATT (CID 4) and SMP (CID 6) fixed channels exposed as ordinary L2CAP sockets. What’s missing is userland: GATT, the SMP agent, LTK storage and HOGP.</li>
<li><strong>Stage 0 is small:</strong> seven stock kernel options, plus <code>vkbd</code> and <code>cuse</code>, compiled into <code>config/NEXTBSD</code> (K1). There is no <code>.ko</code> tree, so nothing can autoload; this is the <code>wlan_xauth</code> trap again.</li>
<li><strong><code>bluetoothd</code> replaces <code>hcsecd</code>.</strong> <code>hcsecd</code> handles three events, has no SSP, and only stores keys for devices already in its config file. <code>bluetoothd</code> supervises stock <code>sdpd</code>, <code>bthidd</code> and <code>virtual_oss</code>, and builds the netgraph graph itself, which is the job <code>devd</code> and <code>rc.d</code> do on stock FreeBSD.</li>
<li><strong>A2DP to headphones is mostly already in base:</strong> <code>virtual_oss</code> moved into FreeBSD 15. HFP (the headset microphone) is the real gap, it starts in the kernel, and it’s parked behind a decision (A6).</li>
<li><strong>Keyboards work pre-login through kbdmux’s evdev node.</strong> Bluetooth mice in a running X are blocked on input hotplug (H4), which goes to a future input-management epic.</li>
</ul></section>
<h2 id="decided">Decided (2026-09-20)</h2><ul>
<li><strong>Classic first on netgraph.</strong> LE comes second, as a thin ATT/GATT/SMP host inside <code>bluetoothd</code> over the kernel’s LE sockets, so it coexists with Classic on one controller. Not NimBLE (it would need the ACL hook and would kill Classic), and not BlueZ.</li>
<li><strong>Everything is compiled into the kernel.</strong> The in-kernel matcher has no USB provider yet, so Bluetooth transports can’t be kexts.</li>
<li><strong>Link keys are stored in plaintext</strong>, in a separate 0600 SCPreferences file isolated for the keychain migration. This is the same accepted debt as WLAN.</li>
<li><strong>Pi 5 / Pi 500: a USB dongle for now.</strong> The onboard CYW43455 needs new UART, GPIO, pinctrl, H4 and patchram work (K7 measures first, K8 is parked).</li>
<li><strong>Out of scope:</strong> non-Bluetooth input and audio device management. H4 and A4 record the interfaces that future epic must provide.</li></ul>
<h2 id="index">Index — all 38 tickets, filed</h2>
<table class="compact"><tr><th>ID</th><th>Issue</th><th>Title</th><th>Size</th><th>Track</th><th>Depends on</th></tr><tr><th colspan="6">Stage 0 — kernel & image</th></tr>
<tr><td><a href="nextbsd-e16-tickets.html#K1"><strong>K1</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-kernel/issues/231">nextbsd-kernel#231</a></td><td>config: bake netgraph + the Bluetooth stack, vkbd and cuse into NEXTBSD — no .ko tree, so nothing can autoload (#412 phase 0)</td><td>S</td><td><span class="pill ok">Ship</span></td><td>—</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#K2"><strong>K2</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/475">nextbsd#475</a></td><td>boot-test: assert the Bluetooth stack is present on both arches (ngctl list/types, net.bluetooth, hccontrol exits 7) and guard the kernel options</td><td>S</td><td><span class="pill ok">Ship</span></td><td>K1</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#K3"><strong>K3</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/476">nextbsd#476</a></td><td>Ship Intel (ibt-*) and Realtek (rtl_bt) Bluetooth firmware in the image, with licences — fetched at assembly like the Pi DTBs</td><td>S</td><td><span class="pill ok">Ship</span></td><td>K1</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#A2"><strong>A2</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/485">nextbsd#485</a></td><td>Ship virtual_oss's Bluetooth backend (`/usr/local/lib/virtual_oss/voss_bt.so`) on the image</td><td>S</td><td><span class="pill ok">Ship</span></td><td>K1</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#A3"><strong>A3</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-kernel/issues/236">nextbsd-kernel#236</a></td><td>kldload(2) of a statically linked module returns ENOENT on NextBSD — virtual_oss dies at `kldload("cuse.ko")` even with cuse baked</td><td>S</td><td><span class="pill ok">Ship</span></td><td>K1</td></tr>
<tr><th colspan="6">Stage 1 — hand verification</th></tr>
<tr><td><a href="nextbsd-e16-tickets.html#K6"><strong>K6</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/477">nextbsd#477</a></td><td>Phase 1: hand-verify the baked stack on real USB dongles (amd64 + Pi 500+ via RP1 xhci) and start the Bluetooth hardware matrix</td><td>S</td><td><span class="pill ok">Ship</span></td><td>K1</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#B4"><strong>B4</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/478">nextbsd#478</a></td><td>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</td><td>S</td><td><span class="pill warn">Needs answer</span></td><td>K1</td></tr>
<tr><th colspan="6">Stage 2 — bluetoothd core</th></tr>
<tr><td><a href="nextbsd-e16-tickets.html#D1"><strong>D1</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/206">nextbsd-userland#206</a></td><td>bluetoothd v0 skeleton: launchd job, Mach service, no-stack/no-adapter idle, `bluetooth status`, CI markers</td><td>M</td><td><span class="pill ok">Ship</span></td><td>—</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#B2"><strong>B2</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/204">nextbsd-userland#204</a></td><td>bluetoothd: engine interface (engine.h) that Classic and LE both implement - typed addresses, one pairing-prompt shape, engine-neutral bond record</td><td>M</td><td><span class="pill ok">Ship</span></td><td>—</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#D2"><strong>D2</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/207">nextbsd-userland#207</a></td><td>bluetoothd: adapter lifecycle — detect ubtN, build the netgraph graph, initialise the controller, publish State:/Bluetooth/Adapter, power on/off</td><td>L</td><td><span class="pill ok">Ship</span></td><td>D1, K1, B2</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#D3"><strong>D3</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/208">nextbsd-userland#208</a></td><td>bluetoothd: Classic inquiry scan with cached results and remote names; `bluetooth scan`</td><td>M</td><td><span class="pill ok">Ship</span></td><td>D2</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#D5"><strong>D5</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/210">nextbsd-userland#210</a></td><td>bluetoothd: SCPreferences persistence — PairedDevices metadata plus a separate 0600 link-key file; `bluetooth list`</td><td>M</td><td><span class="pill ok">Ship</span></td><td>D1</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#D4"><strong>D4</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/209">nextbsd-userland#209</a></td><td>bluetoothd: security manager replacing hcsecd — link-key/PIN replies, SSP (numeric comparison, passkey), pair/unpair RPCs, pull-model user confirmation</td><td>L</td><td><span class="pill ok">Ship</span></td><td>D2, D5</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#D7"><strong>D7</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/212">nextbsd-userland#212</a></td><td>bluetoothd: supervise stock sdpd (and the child-supervision hook bthidd/btpand will use)</td><td>S</td><td><span class="pill ok">Ship</span></td><td>D2</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#D8"><strong>D8</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/213">nextbsd-userland#213</a></td><td>bluetoothd: connect/disconnect, per-device state publishing (State:/Bluetooth/Device), auto-reconnect of paired devices at boot</td><td>M</td><td><span class="pill ok">Ship</span></td><td>D4, D5</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#D6"><strong>D6</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/211">nextbsd-userland#211</a></td><td>bluetooth(8): full CLI — status|list|scan|pair|confirm|unpair|connect|disconnect|power|discoverable, `--no-prompt` exit codes, man pages</td><td>M</td><td><span class="pill ok">Ship</span></td><td>D1, D3, D4, D5, D8</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#D9"><strong>D9</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/480">nextbsd#480</a></td><td>CI: Bluetooth boot-test gates (BT-RPC-OK, BT-CLI-OK, BT-PREFS-OK, BT-NOSTACK→BT-NOADAPTER flip when the kernel bakes netgraph)</td><td>S</td><td><span class="pill ok">Ship</span></td><td>D1</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#K4"><strong>K4</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/202">nextbsd-userland#202</a></td><td>Contract: bluetoothd runs iwmbtfw/rtlbtfw on USB arrival for controllers that boot in bootloader/ROM mode (devd's iwmbtfw.conf/rtlbtfw.conf, without devd)</td><td>M</td><td><span class="pill info">Sequence</span></td><td>K3, D2</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#D10"><strong>D10</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/481">nextbsd#481</a></td><td>Bluetooth hardware bring-up run: first execution of bluetoothd scan/pair/reconnect on a real USB dongle (test matrix + findings)</td><td>S</td><td><span class="pill info">Sequence</span></td><td>D2, D3, D4, D8</td></tr>
<tr><th colspan="6">Stage 3 — keyboards, mice & trackpads (HID)</th></tr>
<tr><td><a href="nextbsd-e16-tickets.html#H2"><strong>H2</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/214">nextbsd-userland#214</a></td><td>bluetoothd: HID profile driver — generate bthidd.conf on pair, supervise bthidd -u, keyboards usable pre-login</td><td>M</td><td><span class="pill ok">Ship</span></td><td>K1, D4, D5, D7</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#H3"><strong>H3</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/215">nextbsd-userland#215</a></td><td>bthidd: reload config on SIGHUP without dropping sessions; rescan all devices per tick (NextBSD patch, upstream candidate)</td><td>S</td><td><span class="pill info">Harden</span></td><td>H2</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#H5"><strong>H5</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/483">nextbsd#483</a></td><td>Bluetooth mice and trackpads in X via per-device uinput nodes (blocked on input hotplug)</td><td>M</td><td><span class="pill info">Sequence</span></td><td>H2, H4</td></tr>
<tr><th colspan="6">Stage 4 — audio</th></tr>
<tr><td><a href="nextbsd-e16-tickets.html#A4"><strong>A4</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/218">nextbsd-userland#218</a></td><td>bluetoothd: A2DP source — on connect of an AudioSink device, run/retarget virtual_oss at `/dev/bluetooth/<addr>`, publish the node, fall back on disconnect</td><td>L</td><td><span class="pill ok">Ship</span></td><td>K1, A2, A3, D1, D8</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#A5"><strong>A5</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/219">nextbsd-userland#219</a></td><td>bluetoothd: A2DP sink — supervise virtual_bt_speaker so a phone can play through the machine's speakers</td><td>M</td><td><span class="pill info">Sequence</span></td><td>K1, A3, D1</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#A7"><strong>A7</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/220">nextbsd-userland#220</a></td><td>bluetoothd: AVRCP target — accept the headset's play/pause/next/volume keys and deliver them to the session</td><td>L</td><td><span class="pill info">Sequence</span></td><td>A4, D1</td></tr>
<tr><th colspan="6">Stage 5 — Bluetooth LE</th></tr>
<tr><td><a href="nextbsd-e16-tickets.html#B5"><strong>B5</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-kernel/issues/234">nextbsd-kernel#234</a></td><td>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</td><td>M</td><td><span class="pill info">Harden</span></td><td>B4, K1</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#B6"><strong>B6</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/205">nextbsd-userland#205</a></td><td>bluetoothd LE engine: GAP scan/connect, ATT/GATT client, SMP pairing agent and LTK responder over the kernel's ATT/SMP sockets</td><td>XL</td><td><span class="pill info">Sequence</span></td><td>B2, D4, B4, B5</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#H7"><strong>H7</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/217">nextbsd-userland#217</a></td><td>Scope HOGP (HID over GATT) for LE-only keyboards/mice — blocked on the Bluetooth engine decision</td><td>XL</td><td><span class="pill bad">Parked</span></td><td>B6</td></tr>
<tr><th colspan="6">Needs an answer</th></tr>
<tr><td><a href="nextbsd-e16-tickets.html#H4"><strong>H4</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/482">nextbsd#482</a></td><td>Decide how Bluetooth HID input reaches X: kern.evdev.rcpt_mask policy and the input-hotplug interface</td><td>S</td><td><span class="pill warn">Needs answer</span></td><td>—</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#A6"><strong>A6</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-kernel/issues/237">nextbsd-kernel#237</a></td><td>Decide: HFP/HSP headset microphone — needs eSCO in ng_hci, alt-setting fix in ng_ubt, sco hook wiring, and a from-scratch HFP daemon (XL)</td><td>XL</td><td><span class="pill warn">Needs answer</span></td><td>K1, A4</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#K7"><strong>K7</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-kernel/issues/232">nextbsd-kernel#232</a></td><td>rpi5: measure what the firmware leaves for the onboard CYW43455 Bluetooth (BT_ON gio 29, uarta pinmux, 96 MHz clock, bdaddr) before any driver work</td><td>S</td><td><span class="pill warn">Needs answer</span></td><td>—</td></tr>
<tr><th colspan="6">Harden — CI without a radio</th></tr>
<tr><td><a href="nextbsd-e16-tickets.html#K5"><strong>K5</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/203">nextbsd-userland#203</a></td><td>btemu: a userland HCI controller on ng_hci's drv hook so CI can exercise hci/l2cap/btsocket and bluetoothd without a radio</td><td>M</td><td><span class="pill info">Harden</span></td><td>K1, K2</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#H8"><strong>H8</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/484">nextbsd#484</a></td><td>CI: synthetic input-path test in qemu (vkbd → kbdmux/evdev, uinput → /dev/input → X) without a radio</td><td>M</td><td><span class="pill info">Harden</span></td><td>K1</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#A8"><strong>A8</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/486">nextbsd#486</a></td><td>Boot-test: prove the Bluetooth-audio plumbing without a radio (cuse, virtual_oss under launchd, backend load, sndstat/sndctl visibility)</td><td>S</td><td><span class="pill info">Harden</span></td><td>K1, A2, A3</td></tr>
<tr><th colspan="6">Docs</th></tr>
<tr><td><a href="nextbsd-e16-tickets.html#B8"><strong>B8</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd/issues/479">nextbsd#479</a></td><td>Docs: correct freebsd-bluetooth-management.html - FreeBSD's kernel already has LE HCI/L2CAP fixed channels and SMP sockets; the gap is userland</td><td>XS</td><td><span class="pill ok">Ship</span></td><td>—</td></tr>
<tr><th colspan="6">Parked</th></tr>
<tr><td><a href="nextbsd-e16-tickets.html#K8"><strong>K8</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-kernel/issues/233">nextbsd-kernel#233</a></td><td>rpi5: onboard Bluetooth over uarta — bcm7271 UART compat, brcmstb-gpio, bcm2712-pinctrl, an H4 transport on ttyhook, BCM4345C0.hcd patchram (parked)</td><td>XL</td><td><span class="pill bad">Parked</span></td><td>K1, K7</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#B7"><strong>B7</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-kernel/issues/235">nextbsd-kernel#235</a></td><td>Spike: price a netgraph LE tee node (route LE connection-handle ACL to a userland ng_socket) that would let a full host like NimBLE run beside kernel Classic</td><td>M</td><td><span class="pill bad">Parked</span></td><td>B4</td></tr>
<tr><td><a href="nextbsd-e16-tickets.html#H6"><strong>H6</strong></a></td><td><a href="https://github.com/nextbsd/nextbsd-userland/issues/216">nextbsd-userland#216</a></td><td>bthidd: Apple Magic Mouse 2 and Magic Trackpad 1/2 vendor reports (scroll, multitouch via uinput)</td><td>L</td><td><span class="pill bad">Parked</span></td><td>H2, H5</td></tr></table><h2 id="area1">Kernel & hardware (K)</h2>
<p style="font-size:.85rem;color:var(--muted)">Deep-dive notes, lightly edited. Draft ids map to issues in the <a href="#index">index</a>.</p>
<p>Scoping notes for nextbsd/nextbsd#473 (epic) and #412 (seed). Read-only research; nothing filed.
Evidence paths: <code>nextbsd-kernel/…</code>, <code>nextbsd/…</code>, <code>ul/…</code> are the local clones; <code>sys/…</code>, <code>usr.sbin/…</code>
are FreeBSD <code>releng/15.1</code> unless marked <code>13.5</code>.</p>
<h4>TL;DR</h4>
<ol>
<li><strong>Seven <code>options</code> lines bake the whole USB Bluetooth stack.</strong> Every token is stock and
machine-independent (<code>sys/conf/files:4299-4320</code>, <code>sys/conf/options:516-526</code>, <code>NOTES:813-818</code>);
the only bus dependency is <code>usb</code>, which GENERIC already has on amd64 and arm64
(<code>sys/arm64/conf/std.dev:101</code>). One change to <code>config/NEXTBSD</code> covers both arches and
NEXTBSD-RPI5 (which <code>include</code>s it, <code>config/NEXTBSD-RPI5:39</code>).</li>
<li><strong>There is exactly one lazy-kldload in the netgraph/BT code:</strong> <code>sys/netgraph/ng_socket.c:281-303</code>
— an <code>NGM_MKPEER</code> for an unregistered type does <code>kern_kldload("ng_<type>")</code>. That is how stock
FreeBSD pulls in <code>ng_hci</code>/<code>ng_l2cap</code> from <code>rc.d/bluetooth</code>. On NextBSD it fails (no <code>.ko</code> tree,
<code>nextbsd-kernel/ci/assemble-image.sh:168</code>). Baking the types makes <code>ng_findtype()</code> succeed before
the fallback is reached, so the path is never taken. The BT directories themselves contain no
<code>kldload</code> at all.</li>
<li><strong>Nothing in the kernel builds the graph.</strong> <code>ng_ubt</code> attaches a bare <code>ubt0</code> node; on stock FreeBSD
<code>sbin/devd/bluetooth.conf</code> runs <code>service bluetooth quietstart ubt0</code>, and <code>rc.d/bluetooth</code>'s
<code>bluetooth_setup_stack()</code> does the <code>mkpeer</code>/<code>connect</code>/<code>hccontrol initialize</code> dance. NextBSD strips
<code>devd</code> and ships no <code>rc.d</code>, so <strong><code>bluetoothd</code> (area 2) owns graph assembly</strong> — the interface is spelled
out in §3.</li>
<li><strong>Firmware is a userland problem, not a firmware(9) problem.</strong> Intel (7260…AX-class, VID 0x8087) and
Realtek controllers ship in bootloader/ROM mode; the in-tree <code>ng_ubt_intel.c</code> / <code>ng_ubt_rtl.c</code> refuse
to attach until <code>iwmbtfw(8)</code> / <code>rtlbtfw(8)</code> have pushed firmware over <code>ugen</code>. The blobs come from
Debian <code>firmware-nonfree</code> (ports <code>comms/iwmbt-firmware</code>, <code>comms/rtlbt-firmware</code>; licences allow
redistribution). The trigger on stock FreeBSD is a devd rule; NextBSD has no devd, launchd's
<code>HardwareMatch</code> is iter-1 (parse only, <code>ul/src/launchd/src/core.c:262-270</code>), so the trigger must be
<code>bluetoothd</code>'s job (interface in §4.5). Broadcom BCM20702/Apple parts work in ROM firmware; the
only Broadcom firmware tool in tree (<code>bcmfw</code>/<code>ubtbcmfw</code>) is for the 2003-era BCM2033 and ships no
firmware — skip it.</li>
<li><strong>Raspberry Pi 5 / Pi 500 onboard Bluetooth is unsupported at every layer in 15.1</strong> and should be
parked. The BT radio hangs off <code>uarta</code> (<code>brcm,bcm7271-uart</code>, an 8250 variant FreeBSD has no compat
entry for), needs <code>brcm,brcmstb-gpio</code> (BT_ON = gio 29) and <code>brcm,bcm2712-pinctrl</code> (neither in tree),
a UART HCI transport (<code>ng_h4</code> removed in 2021, commit 79a100e28e; <code>hcseriald</code> removed 66d6299848),
and a patchram download of <code>BCM4345C0.hcd</code> that FreeBSD has never had. USB dongles over RP1's xhci
are the E16 path on the Pi.</li>
<li><strong>Bake, don't kext.</strong> The in-kernel IOCatalogue matches PCI ids and FDT <code>compatible</code> strings only
(<code>src-overlay/sys/sys/iocatalogue.h:24-31</code>, <code>iokit_catalogue.c:270-279</code>); there is no USB provider,
the personality generators are PCI-only, and the protocol nodes are not devices at all (nothing fires
<code>device_nomatch</code> for them). <code>ng_ubt</code> also fails the delivery plan's own kext rule
(kext ⇐ has-firmware(9) ∨ multi-version). ~10.6k LOC total, order of half a megabyte of kernel.</li>
<li><strong>CI can prove presence, not radio.</strong> QEMU removed Bluetooth emulation in 2019 (commits
1d4ffe8dc7, 43d68d0a94). CI can assert <code>ngctl list</code> shows <code>btsock_hci_raw</code>/<code>btsock_l2c_raw</code>/
<code>btsock_l2c</code>, <code>sysctl net.bluetooth.version</code>, and <code>hccontrol</code> exiting 7 with <code>Could not find HCI
nodes</code> (<code>hccontrol.c:110-112</code>) instead of <code>EAFNOSUPPORT</code>. A userland HCI controller emulator on the
<code>hci</code> node's <code>drv</code> hook (<code>ng_hci.h:62</code>) can exercise the whole protocol stack without a radio — a
worthwhile hardening ticket. Real dongles: <code>qemu -device usb-host,vendorid=…,productid=…</code> on a
Linux host, or real hardware.</li>
</ol>
<hr />
<h4>1. What must be compiled into NEXTBSD</h4>
<h5>1.1 The change</h5>
<pre><code>### config/NEXTBSD (proposed)
options NETGRAPH # netgraph core: ng_base.c, ng_parse.c
options NETGRAPH_SOCKET # ng_socket: PF_NETGRAPH, what ngctl/libnetgraph/hccontrol use to find nodes
options NETGRAPH_BLUETOOTH # ng_bluetooth: net.bluetooth sysctls, shared version/timeouts
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)
options NETGRAPH_BLUETOOTH_UBT # ng_ubt + ng_ubt_intel + ng_ubt_rtl (USB transport)
</code></pre>
<p>Why each is required, with the evidence:</p>
<table>
<thead>
<tr>
<th>Token</th>
<th>Files it gates (<code>sys/conf/files</code>)</th>
<th>Why it cannot be left out</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>NETGRAPH</code></td>
<td><code>netgraph/ng_base.c</code> (:4326), <code>ng_parse.c</code> (:4353)</td>
<td>Every node type <code>MODULE_DEPEND(…, netgraph, …)</code> (e.g. <code>ng_ubt.c:2055</code>, <code>ng_btsocket.c:218</code>). <code>sys/conf/options:516</code></td>
</tr>
<tr>
<td><code>NETGRAPH_SOCKET</code></td>
<td><code>netgraph/ng_socket.c</code> (:4361)</td>
<td><code>hccontrol</code> calls <code>find_hci_nodes()</code> → <code>NgMkSockNode()</code> + <code>NGM_LISTNAMES</code> before it opens the BT socket (<code>usr.sbin/bluetooth/hccontrol/hccontrol.c:110</code>); <code>ngctl(8)</code>, <code>l2ping</code>, <code>sdpcontrol</code>, and <code>bluetoothd</code>'s graph assembly all need PF_NETGRAPH. <code>options:561</code></td>
</tr>
<tr>
<td><code>NETGRAPH_BLUETOOTH</code></td>
<td><code>common/ng_bluetooth.c</code> (:4299)</td>
<td><code>MODULE_DEPEND</code> of <code>ng_hci</code> (<code>ng_hci_main.c:95</code>), <code>ng_l2cap</code> (<code>:95</code>), <code>ng_btsocket</code> (<code>:216</code>), <code>ng_ubt</code> (<code>:2057</code>). Provides <code>net.bluetooth.version</code> and the HCI timeouts (<code>ng_bluetooth.c:59-113</code>)</td>
</tr>
<tr>
<td><code>NETGRAPH_BLUETOOTH_HCI</code></td>
<td><code>hci/ng_hci_*.c</code> (:4304-4308)</td>
<td><code>MODULE_DEPEND(ng_ubt, ng_hci, …)</code> (<code>ng_ubt.c:2056</code>); the <code>hci</code> type must be registered before <code>bluetoothd</code> mkpeers it</td>
</tr>
<tr>
<td><code>NETGRAPH_BLUETOOTH_L2CAP</code></td>
<td><code>l2cap/ng_l2cap_*.c</code> (:4309-4314)</td>
<td>Same: <code>mkpeer ubt0hci: l2cap acl hci</code> (<code>rc.d/bluetooth</code> <code>bluetooth_setup_stack</code>)</td>
</tr>
<tr>
<td><code>NETGRAPH_BLUETOOTH_SOCKET</code></td>
<td><code>socket/ng_btsocket*.c</code> (:4315-4320)</td>
<td><code>DOMAIN_SET(ng_btsocket_)</code> (<code>ng_btsocket.c:248</code>) registers PF_BLUETOOTH. Domains are never autoloaded; without it <code>socket(PF_BLUETOOTH, …)</code> is <code>EAFNOSUPPORT</code> and <code>hccontrol</code> dies with <code>Could not create socket</code> (<code>hccontrol.c:122-124</code>)</td>
</tr>
<tr>
<td><code>NETGRAPH_BLUETOOTH_UBT</code></td>
<td><code>drivers/ubt/ng_ubt.c</code>, <code>ng_ubt_intel.c</code>, <code>ng_ubt_rtl.c</code> — all <code>optional netgraph_bluetooth_ubt usb</code> (:4300-4302)</td>
<td>The USB HCI transport. <code>DRIVER_MODULE(ng_ubt, uhub, …)</code> + <code>USB_PNP_HOST_INFO(ubt_devs)</code> (<code>ng_ubt.c:2053,2059</code>). One token brings all three files, so the Intel/Realtek "refuse to attach in bootloader mode" guards come for free</td>
</tr>
</tbody>
</table>
<p>Deliberately <strong>not</strong> baked:</p>
<ul>
<li><code>NETGRAPH_BLUETOOTH_UBTBCMFW</code> — <code>ubtbcmfw(4)</code> is the 2003 BCM2033 firmware-download cdev
(<code>ubtbcmfw.c:32,66</code>); <code>bcmfw(8)</code> says "Due to copyright issues I will no longer provide mini-driver
and firmware files" (<code>bcmfw.8:54-56</code>). Dead weight.</li>
<li><code>NETGRAPH_BLUETOOTH_H4</code> / <code>_BT3C</code> — the option tokens still exist (<code>sys/conf/options:520-521</code>) but
gate no files: <code>ng_h4</code> and <code>ng_bt3c</code> are gone in 14+ (§5).</li>
<li>Any of the other 40 <code>NETGRAPH_*</code> node types (<code>options:517-570</code>). None is a BT dependency.</li>
</ul>
<h5>1.2 Module dependency check (both arches)</h5>
<p>All <code>MODULE_DEPEND</code>s in the BT tree resolve inside the set above plus <code>usb</code>:
<code>ng_ubt</code>→{netgraph, ng_hci, ng_bluetooth, usb} (<code>ng_ubt.c:2055-2058</code>), <code>ng_ubt_intel</code>/<code>ng_ubt_rtl</code>→{netgraph, ng_hci, usb}
(<code>ng_ubt_intel.c:288-290</code>, <code>ng_ubt_rtl.c:270-272</code>), <code>ng_hci</code>/<code>ng_l2cap</code>→ng_bluetooth, <code>ng_btsocket</code>→{ng_bluetooth, netgraph}.
<code>device usb</code> is in amd64 GENERIC and in arm64 <code>std.dev:101</code> (<code>device usb # USB Bus (required)</code>), which arm64 GENERIC includes (<code>sys/arm64/conf/GENERIC:24</code>).
The Pi 5's USB is behind RP1 (<code>patches/0018-…</code>, <code>0020-…</code>) and the Pi 500+ already runs a USB keyboard through it, so <code>ng_ubt</code> on a dongle has a working <code>uhub</code> parent there.</p>
<p><strong>amd64 vs arm64: no difference.</strong> All tokens are in the MI <code>sys/conf/files</code>/<code>options</code>, not <code>files.amd64</code>/<code>files.arm64</code>. Neither GENERIC carries any of them (<code>grep -i netgraph sys/amd64/conf/GENERIC</code> and <code>sys/arm64/conf/GENERIC</code> are empty), so this is purely additive on both. NEXTBSD-RPI5 inherits via <code>include NEXTBSD</code>.</p>
<h5>1.3 Cost</h5>
<p>Source: 10,578 lines for <code>ng_base.c</code> + <code>ng_socket.c</code> + every file under <code>netgraph/bluetooth/</code> (measured, <code>wc -l</code>).
Binary: <strong>not measured here</strong> — no build in this session. From memory of stock 14.x <code>.ko</code> sizes the resident text+data is on the order of 0.4–0.5 MB (netgraph ≈ 115K, ng_btsocket ≈ 105K, ng_hci/ng_l2cap ≈ 80K each, ng_ubt ≈ 40K, ng_socket ≈ 20K, ng_bluetooth ≈ 10K). K1's acceptance asks for the real <code>size(1)</code> delta on the CI kernel. Against the ~120 MB wired baseline the delivery plan measured, it is noise. On a machine with no radio the code is never entered beyond the SYSINIT that registers types and the <code>btsock_*</code> nodes.</p>
<h5>1.4 Hidden lazy-load paths</h5>
<p>Grep of <code>sys/netgraph/**</code> for <code>kern_kldload|kldload|linker_load|modfind</code>:</p>
<ul>
<li><strong><code>sys/netgraph/ng_socket.c:281-303</code></strong> — the only hit. Inside <code>ngc_send()</code>: if a message is <code>NGM_MKPEER</code> and <code>ng_findtype(mkp->type) == NULL</code>, it does <code>kern_kldload(curthread, "ng_<type>", &fileid)</code>; on failure the mkpeer errors out (<code>ENOENT</code>/<code>ENXIO</code>). This is how stock FreeBSD's <code>rc.d/bluetooth</code> (<code>required_modules="ng_bluetooth ng_hci ng_l2cap ng_btsocket"</code>, line 8, plus the mkpeers) works without anything in the kernel config. On NextBSD the kldload can never succeed; with the types baked, <code>ng_findtype()</code> succeeds and the branch is skipped. This should be added to the kernel#52 audit table.</li>
<li><strong>None in <code>sys/netgraph/bluetooth/</code></strong>. <code>ng_ubt</code> attach only creates the <code>ubt</code> node; it never loads or mkpeers <code>hci</code>.</li>
<li>Userland side: <code>rc.d/bluetooth</code> is itself a kldload consumer (<code>required_modules</code>), but NextBSD runs no rc.d, so it is irrelevant except as the reference for what <code>bluetoothd</code> must do.</li>
</ul>
<hr />
<h4>2. What the kernel gives you, and what it does not</h4>
<p>After K1, plugging in a class-<code>E0/01/01</code> dongle yields:</p>
<pre><code>ubt0 on uhub0
ubt0: <vendor product> on usbus0
</code></pre>
<p>and a netgraph node <code>ubt0:</code> of type <code>ubt</code> with one hook, <code>hook</code>. <strong>Nothing else.</strong> No <code>ubt0hci</code>, no L2CAP, no socket wiring, no HCI reset. On stock FreeBSD that is done by:</p>
<ul>
<li><code>sbin/devd/bluetooth.conf</code>: <code>attach 100 { device-name "ubt[0-9]+"; action "service bluetooth quietstart $device-name"; }</code> (and <code>quietstop</code> on detach).</li>
<li><code>libexec/rc/rc.d/bluetooth</code> <code>bluetooth_setup_stack()</code>: <code>ngctl mkpeer ${dev}: hci ${hook} drv</code> → <code>ngctl name ${dev}:${hook} ${dev}hci</code> → <code>mkpeer ${dev}hci: l2cap acl hci</code> → <code>name … ${dev}l2cap</code> → <code>connect ${dev}hci: btsock_hci_raw: raw ${dev}raw</code> → <code>connect ${dev}l2cap: btsock_l2c_raw: ctl ${dev}ctl</code> → <code>connect ${dev}l2cap: btsock_l2c: l2c ${dev}l2c</code> → <code>hccontrol -n ${dev}hci reset</code> (3 tries) → <code>read_bd_addr</code>, <code>read_local_supported_features</code>, <code>read_buffer_size</code>, <code>write_scan_enable</code>, <code>write_class_of_device</code>, <code>write_authentication_enable</code>, <code>write_encryption_mode</code>, <code>write_node_role_switch</code>, <code>change_local_name</code>, <code>initialize</code>.</li>
</ul>
<p>NextBSD strips <code>/sbin/devd</code> and <code>/sbin/devmatch</code> from the base (nextbsd-freebsd-compat README, "Superseded base tools": replaced by <code>kextd</code> + libIOKit) and never installs <code>/etc/rc.d</code>. So this is an <strong>interface to area 2</strong>: <code>bluetoothd</code> must subscribe to device arrival (libIOKit <code>IOKitNotify</code> / the kernel registry, the same path <code>diskarbitrationd</code> uses in <code>ul/src/DiskArbitration/da_iokit_subscribe.c</code>), and on <code>ubt%d</code> arrival run the equivalent of <code>bluetooth_setup_stack()</code> through libnetgraph (<code>NgMkSockNode</code> + <code>NgSendMsg</code>), then the HCI init sequence. Until it exists, §8's hand recipe does it with <code>ngctl</code>.</p>
<p>Good news on the userland tools: the compat base is a full <code>buildworld</code> with only <code>WITHOUT_TOOLCHAIN/TESTS/LIB32/DEBUG_FILES</code> (nextbsd-freebsd-compat <code>.github/workflows/build.yml:30-31</code>, README "What it builds"), and <code>MK_BLUETOOTH</code>/<code>MK_NETGRAPH</code> default to yes (<code>share/mk/src.opts.mk:70,150</code>; <code>MK_BLUETOOTH</code> is only forced off when <code>MK_NETGRAPH=no</code>, <code>:444-445</code>). So <code>hccontrol</code>, <code>l2ping</code>, <code>l2control</code>, <code>sdpcontrol</code>, <code>sdpd</code>, <code>hcsecd</code>, <code>bthidd</code>, <code>bthidcontrol</code>, <code>iwmbtfw</code>, <code>rtlbtfw</code>, <code>ngctl</code>, <code>libbluetooth</code>, <code>libsdp</code>, <code>libnetgraph</code> should already be in <code>nextbsd-base-<arch>.tar.gz</code>. <strong>Not verified on an image</strong> — the site's srclist plan (<code>site/freebsd-srclist-build-plan.html</code>) marks <code>usr.sbin/ngctl</code> as DEFER, but that plan is not what the compat repo builds today. K1's acceptance includes <code>ls /usr/sbin/hccontrol /usr/sbin/ngctl</code> on the CI image so this is settled by evidence.</p>
<hr />
<h4>3. Controllers, chipsets, firmware</h4>
<h5>3.1 What <code>ng_ubt</code> claims (<code>sys/netgraph/bluetooth/drivers/ubt/ng_ubt.c</code>)</h5>
<ul>
<li>Generic: any interface with class <code>UDCLASS_WIRELESS</code> (0xE0) / subclass <code>UDSUBCLASS_RF</code> (0x01) / protocol <code>UDPROTO_BLUETOOTH</code> (0x01) — <code>ubt_devs[]:452-455</code>. This is every standards-conforming dongle (CSR, Cambridge, Qualcomm/CSR8510, modern Intel/Realtek/MediaTek once firmware is up).</li>
<li>Vendor-class Broadcom (<code>USB_VENDOR_BROADCOM</code> + <code>UICLASS_VENDOR</code>/<code>UDSUBCLASS_RF</code>, <code>:460-463</code>), Apple (<code>:466-469</code>, i.e. every Mac's BCM20702/BCM4360-family combo card), Foxconn (<code>:473-475</code>), plus explicit BCM20702A0 ids (ASUS/Lite-On/Foxconn/Dell/Belkin, <code>:520-526</code>) and legacy TDK/ALPS/Ericsson/Canyon.</li>
<li><code>ubt_ignore_devs[]:392-446</code>: AVM BlueFritz v1, Atheros AR3011/AR3012/AR9285/AR5BBU12 with <em>sflash</em> firmware (need <code>ath3kfw</code>), all twelve Intel ids (handed to <code>ng_ubt_intel.c</code>), AzureWave 3602/3604. <code>ubt_rtl_devs</code> are likewise refused by the base probe (<code>:625-627</code>) and handled by <code>ng_ubt_rtl.c</code>.</li>
<li>Probe returns <code>BUS_PROBE_GENERIC</code> (<code>:638,641</code>), so a more specific driver can outbid it.</li>
</ul>
<p><strong>Broadcom patchram</strong>: <code>ng_ubt</code> contains no patchram/<code>.hcd</code> download (grep <code>broadcom|BCM</code> in the file shows only id tables). Linux's <code>btbcm</code> would push a <code>.hcd</code> into BCM20702/BCM4350-class parts; FreeBSD runs them on ROM firmware. They work (Macs have run FreeBSD BT this way for years) but with whatever bugs the ROM has and no vendor updates. Not an E16 blocker; noted as a known gap.</p>
<h5>3.2 Intel — <code>ng_ubt_intel.c</code> + <code>iwmbtfw(8)</code></h5>
<ul>
<li>Devices: VID 0x8087 PIDs <code>07dc,0a2a,0aa7</code> (7260/7265), <code>0a2b,0aaa,0025,0026,0029</code> (8260/8265/9260-era), <code>0032,0033,0035,0036</code> (9260/9560/AX-class) — <code>ng_ubt_intel.c:89-105</code>.</li>
<li>Behaviour: the probe issues vendor HCI reads (<code>Intel_Read_Version</code>, TLV image type) and returns <code>ENXIO</code> while the part is in bootloader mode (<code>:193-270</code>), because attaching the stack then "locks the adapter hardly so it requires power on/off cycle to restore" (<code>:33-37</code>). Once <code>iwmbtfw</code> has loaded operational firmware the device re-enumerates and <code>ng_ubt</code> attaches normally.</li>
<li>Firmware: <code>iwmbtfw -d <ugenN.M> -f <dir></code> (<code>iwmbtfw.8:59-61</code>: "available in the comms/iwmbt-firmware port"). The port pulls <code>firmware-iwlwifi_<date>_all.deb</code> from Debian <code>non-free-firmware</code> and installs <code>usr/lib/firmware/intel/ibt-*</code> (<code>.sfi</code> + <code>.ddc</code>) to <code>/usr/local/share/iwmbt-firmware</code> (<code>comms/iwmbt-firmware/Makefile</code>; <code>LICENSE=INTEL</code>, <code>LICENSE_PERMS= dist-mirror dist-sell pkg-mirror pkg-sell auto-accept</code>). Redistribution is fine; the set is large (many <code>ibt-*</code> variants — <strong>size not measured</strong>, K3 asks for it).</li>
<li>Trigger on stock FreeBSD: <code>usr.sbin/bluetooth/iwmbtfw/iwmbtfw.conf</code> — devd <code>notify</code> on <code>system USB / subsystem DEVICE / type ATTACH / vendor 0x8087 / product (…12 ids…)</code> → <code>/usr/sbin/iwmbtfw -d $cdev -f /usr/local/share/iwmbt-firmware</code>.</li>
</ul>
<h5>3.3 Realtek — <code>ng_ubt_rtl.c</code> + <code>rtlbtfw(8)</code></h5>
<ul>
<li>Devices: all of <code>USB_VENDOR_REALTEK</code> class E0/01/01 plus ~40 explicit VID/PIDs (<code>ng_ubt_rtl.c:69-169</code>); the probe reads <code>HCI_Read_Local_Version</code> and refuses (<code>ENXIO</code>) when <code>lmp_subversion</code> is in the "ROM firmware incompatible with ng_ubt" list (<code>:172-181, 248-250</code>).</li>
<li>Firmware: <code>rtlbtfw -d <ugen> -f <dir></code>; port <code>comms/rtlbt-firmware</code> (Debian <code>firmware-realtek_<date>_all.deb</code> → <code>usr/lib/firmware/rtl_bt/*</code>, <code>LICENSE=REALTEK</code>, same permissive <code>LICENSE_PERMS</code>). Small (a few MB).</li>
<li>Trigger: <code>usr.sbin/bluetooth/rtlbtfw/rtlbtfw.conf</code> — 365 lines of devd <code>notify</code> rules: generic <code>vendor 0x0bda</code> + <code>interface 0</code> + <code>intclass 0xe0/intsubclass 0x01/intprotocol 0x01</code>, then per-chip ids for 8821CE/8851BE/8852AE/8852BE/8852CE/8922AE/8723AE/BE/BU/DE/8761BUV/8821AE/8822BE/8822CE (VIDs 0x13d3, 0x0489, 0x04ca, 0x04c5, 0x0cb8, 0x0b05, 0x2357, 0x7392, …).</li>
</ul>
<h5>3.4 Others</h5>
<ul>
<li><strong>Atheros AR3011/AR3012</strong> (<code>ath3kfw(8)</code>): firmware "available in the linux-firmware RPM" (<code>ath3kfw.8:57</code>), no port, devd rule is a commented-out example in <code>sbin/devd/devd.conf:71-76</code>. Rare today; park.</li>
<li><strong>MediaTek MT7921/7922 combo (0x0e8d)</strong>: class E0/01/01 so <code>ng_ubt</code> claims it, but those parts need an <code>mt7921</code>-style firmware push FreeBSD has no tool for; expect a non-functional attach. Flagged, unverified.</li>
<li><strong>BCM2033</strong> (<code>ubtbcmfw</code>/<code>bcmfw</code>): skip (§1.1).</li>
</ul>
<h5>3.5 How NextBSD ships firmware today, and why BT is different</h5>
<ul>
<li>The image assembly deletes <code>/boot/firmware</code> and the <code>.ko</code> tree (<code>nextbsd-kernel/ci/assemble-image.sh:168-169</code>); nextbsd#392 is about a stray <code>/boot/firmware/iwm*</code> that crept back.</li>
<li>Kernel-consumed firmware lives inside the kext bundle (<code>Contents/Resources/firmware/</code>) and is found by <code>firmware(9)</code> via patch <code>0004-NextBSD-search-firmware_path-for-raw-firmware-images.patch</code> (kernel#12/#13; IntelWiFi.kext carries 267 MB this way per the WLAN plan).</li>
<li><strong>Bluetooth firmware is consumed by userland tools reading files from a directory</strong>, not by <code>firmware(9)</code>. <code>ng_ubt_intel.c</code> deliberately does <em>not</em> download; it just refuses to attach. So the kext firmware path does not apply and there is no kext to hang it on (§6).</li>
<li>Precedent for non-pkg blobs fetched at image build time already exists: <code>nextbsd/build.sh:444-482</code> fetches the Pi DTBs and <code>LICENCE.broadcom</code> from <code>raspberrypi/firmware</code> at a pinned tag, and ships the licence next to them. K3 does the same for <code>ibt-*</code> and <code>rtl_bt/*</code> from Debian's <code>firmware-nonfree</code> pool (the ports' own <code>MASTER_SITES</code>), into <code>/usr/share/firmware/bluetooth/{intel,rtl_bt}</code> plus the two <code>copyright</code> files. Alternative considered: a data-only <code>org.nextbsd.firmware.bluetooth</code> bundle under <code>/System/Library/Extensions</code> — consistent with the naming plan, but OSKext authentication (<code>assemble-image.sh:199-202</code>) and kextd would have to tolerate an executable-less bundle for no functional gain. Recommend the plain directory.</li>
</ul>
<h5>3.6 The trigger problem (interface to area 2)</h5>
<p>On stock FreeBSD devd runs the loader on USB attach. On NextBSD:</p>
<ul>
<li><code>devd</code> is stripped (compat README).</li>
<li>launchd's <code>HardwareMatch</code> is <strong>iter 1: parse and store only</strong>; the criteria are <code>name</code>/<code>class</code>/<code>driver</code>, and "iter 2 registers them against hwregd's watch RPC and dispatches" (<code>ul/src/launchd/src/core.c:262-270, 6014-6047</code>). There is no <code>hwregd</code> daemon in <code>ul/src</code> (only libIOKit consumers reference the name). Even at iter 2, the criteria cannot express VID/PID.</li>
<li>The in-kernel IOCatalogue reacts to <code>device_nomatch</code> for PCI and FDT only (§6). An Intel part in bootloader mode is a <code>ugen</code> with no driver, which is exactly a nomatch — but there is no USB provider to hang a personality on.</li>
</ul>
<p>So the trigger belongs to <code>bluetoothd</code>: subscribe to USB device arrival via libIOKit, match the union of <code>iwmbtfw.conf</code>/<code>rtlbtfw.conf</code> ids (or simply "VID 0x8087 or 0x0bda, or class E0/01/01 with no <code>ubt</code> sibling after N ms"), run <code>/usr/sbin/iwmbtfw|rtlbtfw -d ugenX.Y -f /usr/share/firmware/bluetooth/<vendor></code>, and expect the device to detach/re-attach as <code>ubtN</code>. K4 records this contract for the daemon ticket set. An in-kernel port of Linux <code>btintel</code>/<code>btrtl</code> into <code>ng_ubt_*</code> (which would let <code>firmware(9)</code> + a kext bundle work) is the long-term "right" shape but is thousands of lines and not needed for E16.</p>
<hr />
<h4>4. Raspberry Pi 5 / Pi 500 onboard Bluetooth</h4>
<h5>4.1 The hardware, from the vendor device tree</h5>
<p><code>raspberrypi/linux</code> <code>rpi-6.6.y</code> (the tree whose <code>bcm2712.dtsi</code> still carries the SoC UART nodes; the <code>rpi-6.12.y</code> copy has moved them into includes):</p>
<ul>
<li><code>bcm2712-rpi-5-b.dts:365-380</code>: <code>/* uarta communicates with the BT module */ &uarta { uart-has-rtscts; auto-flow-control; clock-frequency = <96000000>; pinctrl-0 = <&uarta_24_pins &bt_shutdown_pins>; bluetooth { compatible = "brcm,bcm43438-bt"; max-speed = <3000000>; shutdown-gpios = <&gio 29 GPIO_ACTIVE_HIGH>; local-bd-address = [00 00 00 00 00 00]; }; }</code>. The Pi 500 dts <code>#include</code>s the 5-B dts (<code>bcm2712-rpi-500.dts:2</code>), so same wiring. <code>krnbt</code> (<code>bcm2712-rpi.dtsi:220</code>) and <code>bdaddr</code> (<code>:177</code>) are the config.txt overrides on that node.</li>
<li><code>bcm2712.dtsi:510-519</code> (6.6.y): <code>uarta: serial@7d50c000 { compatible = "brcm,bcm7271-uart"; reg-shift = <2>; reg-io-width = <4>; interrupts = <GIC_SPI 276>; skip-init; }</code> — physical <code>0x107d50c000</code>. <strong>Not</strong> the PL011: the debug console NextBSD uses is <code>uart10: serial@7d001000</code> (<code>arm,pl011</code>, <code>bcm2712.dtsi:241-249</code>, <code>config/rpi5.env</code>).</li>
<li><code>bcm2712.dtsi:497-508</code>: <code>gio: gpio@7d508500 { compatible = "brcm,brcmstb-gpio"; brcm,gpio-bank-widths = <32 22>; }</code> — BT_ON is line 29 here (not on RP1's GPIO, which NextBSD already drives with patch 0025/0048).</li>
<li><code>bcm2712.dtsi:402-…</code>: <code>pinctrl: pinctrl@7d504100 { compatible = "brcm,bcm2712-pinctrl"; uarta_24_pins { pin_rts { function="uart0"; pins="gpio24" }; pin_cts { pins="gpio25" } … }</code> and <code>bt_shutdown_pins { function="gpio"; pins="gpio29" }</code> (<code>bcm2712-rpi-5-b.dts:354-357</code>).</li>
</ul>
<h5>4.2 What FreeBSD 15.1 has for each piece</h5>
<table>
<thead>
<tr>
<th>Piece</th>
<th>Status in 15.1</th>
<th>Evidence</th>
</tr>
</thead>
<tbody>
<tr>
<td>UART driver for <code>brcm,bcm7271-uart</code></td>
<td><strong>None.</strong> <code>uart_dev_ns8250.c</code>'s FDT table is <code>ns16550</code>/<code>ns16550a</code> only (<code>:527-528</code>); the DT node carries no such fallback. <code>sys/dev/uart/</code> has no <code>uart_dev_bcm7271.c</code>. <code>reg-shift</code>/<code>reg-io-width</code> <em>are</em> honoured generically (<code>uart_bus_fdt.c:87,96</code>), so an added compat entry with a 96 MHz rclk may be enough for basic TX/RX — the bcm7271 auto-flow-control and >115200 behaviour are unverified</td>
<td><code>sys/dev/uart</code> listing</td>
</tr>
<tr>
<td>GPIO for BT_ON (<code>brcm,brcmstb-gpio</code>)</td>
<td><strong>None.</strong> <code>sys/dev/gpio/</code> has no brcmstb driver; <code>files.arm64:570-595</code> has only the 2837/2838 <code>bcm2835_gpio</code>/<code>raspberrypi_gpio</code>, and NEXTBSD-RPI5 switches those SoC options <em>off</em> (<code>config/NEXTBSD-RPI5:63-64</code>)</td>
<td><code>sys/conf/files.arm64</code></td>
</tr>
<tr>
<td>Pinctrl (<code>brcm,bcm2712-pinctrl</code>)</td>
<td><strong>None</strong> (the RP1 pinmux is patched in, <code>0048-rp1_gpio-implement-fdt-pinctrl…</code>; the SoC-side one is not)</td>
<td></td>
</tr>
<tr>
<td>UART HCI transport (H4)</td>
<td><strong>Removed.</strong> <code>ng_h4</code> deleted 2021-09-05, commit 79a100e28e ("disconnected 13 years ago … completely fails to compile … Bluetooth has largely (completely?) moved on from bluetooth over UART transport"); <code>hcseriald</code> removed 66d6299848. Present in <code>releng/13.5</code> (<code>sys/netgraph/bluetooth/drivers/h4/ng_h4.c</code>, 1019 lines, old <code>linesw</code> line discipline — <code>ng_h4.c:98-107</code>), absent in 14.0+. A rewrite would follow <code>ng_tty(4)</code>'s <code>ttyhook</code> pattern (<code>sys/netgraph/ng_tty.c:47,116-121</code>), which is alive in 15.1</td>
<td><code>gh api search/commits</code></td>
</tr>
<tr>
<td>Patchram (firmware download)</td>
<td><strong>Never existed on FreeBSD.</strong> Linux <code>btbcm</code> sends <code>BCM4345C0.hcd</code> (63,806 bytes, <code>RPi-Distro/bluez-firmware</code> <code>debian/firmware/broadcom/</code>) over HCI vendor commands (<code>0xFC2E</code> download-minidriver, then the <code>.hcd</code> records, then <code>0xFC18</code> baud update) before the stack starts. Licence: "CYPRESS WIRELESS CONNECTIVITY DEVICES DRIVER END USER LICENSE AGREEMENT", Debian <code>non-free-firmware</code>; Raspberry Pi confirms it is released "on the expectation that we will release them to our users" (<code>debian/copyright:19-131</code>). Redistributable with the licence text, same class as <code>LICENCE.broadcom</code> the image already ships</td>
<td></td>
</tr>
<tr>
<td>BD address</td>
<td><code>local-bd-address</code> is all-zeros in the DT; on Linux the Pi firmware patches it (<code>bdaddr</code> override) and <code>btbcm</code> applies it with vendor cmd <code>0xFC01</code>. Without that the ROM default (<code>43:45:C0:00:1F:AC</code>) is shared by every board</td>
<td></td>
</tr>
<tr>
<td>3 Mbaud + RTS/CTS</td>
<td>Needs the bcm7271 clock (96 MHz from the board dts) and hardware flow control; whether <code>uart(4)</code>'s ns8250 path drives auto-flow on this block is unverified</td>
<td></td>
</tr>
<tr>
<td>Power/mux state left by the Pi firmware</td>
<td><strong>Unknown.</strong> Whether <code>start4.elf</code>/EEPROM leaves gio 29 high and gpio24-27 muxed to uart0 (Linux <code>hci_bcm</code> toggles the shutdown GPIO itself). K7 measures this before anyone writes a driver</td>
<td>needs-hardware</td>
</tr>
</tbody>
</table>
<h5>4.3 Verdict</h5>
<p>Five independent missing pieces (UART compat/clock, brcmstb-gpio, bcm2712-pinctrl, an H4 transport rebuilt on ttyhook, a patchram tool + firmware packaging), plus a BD-address fix-up, plus an <code>hcseriald</code> equivalent that has to be owned by <code>bluetoothd</code>. Every one is a first for FreeBSD. That is XL and off E16's critical path. kernel#99 (BCM43455 WiFi over SDIO) shares the chip but not a single line of this — the BT interface is a separate UART.</p>
<p><strong>Recommendation:</strong> park (K8) behind a measurement spike (K7). For E16 the supported Pi path is a USB dongle in one of RP1's xhci ports, which exercises exactly the baked stack from §1. Say so in the epic so nobody expects the onboard radio to light up.</p>
<hr />
<h4>5. Kext or baked? — Recommendation: <strong>bake all of it</strong></h4>
<p>The driver-delivery plan's rule (<code>site/nextbsd-driver-delivery-plan.html</code> §3): three tiers, and "kext ⇐ has-firmware ∨ needs-multi-version"; otherwise compiled-in or plain kld. Applying it:</p>
<ol>
<li><strong>The protocol nodes (<code>ng_hci</code>, <code>ng_l2cap</code>, <code>ng_btsocket</code>, <code>ng_bluetooth</code>, netgraph itself) are not device drivers.</strong> They are created by <code>NGM_MKPEER</code> from userland; no <code>device_nomatch</code> ever fires for them, so neither the IOCatalogue nor <code>kextd</code> would ever be asked to load them. The only "autoload" mechanism is <code>ng_socket.c</code>'s <code>kern_kldload</code> hack, and turning that into a kextd Mach request is a new kernel feature for no benefit. They must be baked.</li>
<li><strong><code>ng_ubt</code> cannot be matched by the catalogue today.</strong> <code>iocatalogue.h:24-31</code> defines exactly <code>IOCAT_PROVIDER_IOPCIDEVICE</code> and <code>IOCAT_PROVIDER_IOPLATFORMDEVICE</code> (FDT <code>compatible</code>); the nomatch work item carries a PCI <code>match_word</code> "0 if FDT" and a <code>compat[]</code> string (<code>iokit_catalogue.c:270-279</code>). The six <code>gen-*-personalities.sh</code> in nextbsd-kernel-extensions all emit <code>IOProviderClass IOPCIDevice</code>. Matching on USB class <code>E0/01/01</code> (<code>IOUSBInterface</code> + <code>bInterfaceClass</code>/<code>bInterfaceSubClass</code>/<code>bInterfaceProtocol</code>, or <code>idVendor</code>/<code>idProduct</code>) is a new provider kind, a new capture path on the USB nomatch, and a new generator — real work that E16 does not need.</li>
<li><strong><code>ng_ubt</code> fails the kext bar anyway.</strong> It carries no <code>firmware(9)</code> firmware (Intel/Realtek firmware goes through userland tools, §3), and there is one version of it. ~2,600 LOC across the three files.</li>
<li><strong>Cost of baking is small</strong> (§1.3) and the code is inert without a radio.</li>
</ol>
<p>Where a kext <em>would</em> fit later: an IOUSBDevice provider in the catalogue is worth having for the general USB-driver population (audio, serial, WLAN dongles), and <code>ng_ubt</code> could move out then. That is a K-series feature, not an E16 one — listed as an open question, not a ticket. For the Pi 5 UART transport, the BT node is a child of a UART node with no bus driver enumerating it, so it too would be baked into NEXTBSD-RPI5 whenever it exists.</p>
<hr />
<h4>6. Testing</h4>
<h5>6.1 What is and is not possible</h5>
<ul>
<li><strong>QEMU has no Bluetooth.</strong> The core BT emulation and the <code>usb-bt-dongle</code> device were removed in November 2019 (qemu commits 1d4ffe8dc7 "Remove the core bluetooth code", 43d68d0a94 "hw/usb: Remove the USB bluetooth dongle device"; shipped in 4.2). There is nothing to emulate against.</li>
<li><strong>USB host passthrough works</strong> on a Linux host: <code>-device usb-host,vendorid=0x0a12,productid=0x0001</code> (qemu <code>docs/system/devices/usb.rst:160-165</code>, <code>:318-330</code>), given <code>/dev/bus/usb</code> permissions and an xhci/ehci controller in the guest (<code>-device qemu-xhci</code> is already how the boot tests get USB). On macOS/HVF (nextbsd#408 runs the harness there) libusb passthrough requires detaching the host driver and is unreliable — treat it as a developer convenience, not CI. GitHub-hosted runners have no dongle either way.</li>
<li><strong>Real hardware is the real test</strong>, exactly as the WLAN plan said (<code>nextbsd-wlan-plan.html:45</code>).</li>
</ul>
<h5>6.2 What CI can prove without a radio (K2)</h5>
<p>After K1, on the existing qemu boot test (<code>nextbsd/tests/boot-test.sh</code>, both arches):</p>
<pre><code>ngctl list # must show btsock_hci_raw, btsock_l2c_raw, btsock_l2c (and a
# `ngctl(pid)` socket node) — the ng_btsocket nodes exist at boot
# (ng_btsocket_hci_raw.c:197-207 creates and names them at init)
ngctl types # must list types hci, l2cap, ubt, socket (registered by NETGRAPH_INIT)
sysctl -n net.bluetooth.version # prints NG_BLUETOOTH_VERSION (ng_bluetooth.c:59-62); ENOENT before K1
hccontrol read_bd_addr; echo $? # exit 7, stderr "Could not find HCI nodes" (hccontrol.c:110-112)
# NOT "Could not create socket: Address family not supported…"
l2ping -a 00:00:00:00:00:01 # must fail on the connect, not on socket(2)
ls /usr/sbin/hccontrol /usr/sbin/ngctl /usr/sbin/iwmbtfw /usr/sbin/rtlbtfw /usr/sbin/sdpd /usr/sbin/bthidd
</code></pre>
<p>Plus the guard that the WLAN plan asked for in kernel#52: fail the kernel build if <code>config -x</code> of the built kernel lacks any of the seven options.</p>
<h5>6.3 A controller emulator (K5, hardening)</h5>
<p><code>ng_hci</code> does not care what is on its <code>drv</code> hook (<code>ng_hci.h:62</code>: <code>"drv" /* Driver <-> HCI */</code>). A userland process can <code>NgMkSockNode()</code>, <code>mkpeer . hci <hook> drv</code>, name it <code>emu0hci</code>, wire <code>l2cap</code> and the <code>btsock_*</code> nodes exactly as <code>rc.d/bluetooth</code> does, and then answer HCI commands arriving on its data socket with Command Complete events (Reset, Read_BD_ADDR, Read_Local_Supported_Features, Read_Buffer_Size, Write_Scan_Enable, …), and optionally fake an inquiry result and an ACL connection. That runs the whole <code>ng_hci</code>/<code>ng_l2cap</code>/<code>ng_btsocket</code> path plus <code>hccontrol</code>/<code>l2ping</code>/<code>sdpd</code> in qemu with no hardware — the Bluetooth analogue of a loopback interface, and the only way CI will ever exercise <code>bluetoothd</code>'s state machine before real dongles do. ~400 LOC of C over libnetgraph. Linux has the same thing (<code>vhci</code>/<code>btvirt</code>); FreeBSD never grew one.</p>
<hr />
<h4>7. Phase 1 hand-verification recipe (real dongle, after K1)</h4>
<p>Class-E0 CSR/Cambridge dongles (<code>0a12:0001</code>) are the zero-firmware baseline; test Intel/Realtek only after K3/K4.</p>
<pre><code>### 0. enumeration
usbconfig # ugenX.Y: <…> … cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON
dmesg | grep ubt # ubt0 on uhubN
ngctl list # ubt0 (type ubt), btsock_* nodes
### 1. build the graph by hand (what bluetoothd will do; verbatim from rc.d/bluetooth)
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
### 2. bring the controller up
hccontrol -n ubt0hci reset
hccontrol -n ubt0hci read_bd_addr # BD_ADDR: xx:xx:xx:xx:xx:xx <- the real proof
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 # discoverable + connectable
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 # must be "up"
### 3. see the world
hccontrol -n ubt0hci inquiry # lists BD_ADDR + class of nearby discoverable devices
hccontrol -n ubt0hci remote_name_request <addr> 0 0 0
### 4. L2CAP + SDP against a phone/headset in pairing mode
l2ping -a <addr> # 44 bytes from … seq_no=0 time=… ms result=0
sdpcontrol -a <addr> browse # service records (Handsfree, A2DP sink, HID, …)
### 5. teardown (what bluetoothd does on detach)
ngctl shutdown ubt0hci:
ngctl shutdown ubt0l2cap:
</code></pre>
<p>Intel/Realtek addendum (after K3): <code>usbconfig</code> shows the part with <strong>no</strong> <code>ubt</code> sibling; run
<code>iwmbtfw -d ugenX.Y -f /usr/share/firmware/bluetooth/intel</code> (or <code>rtlbtfw … /rtl_bt</code>), watch the device
detach and come back as <code>ubt0</code>, then continue from step 1. Pairing (<code>hcsecd</code>), HID (<code>bthidd</code>) and
audio are areas 2–4.</p>
<p>Record the result in the hardware matrix (K6): dongle ids, arch, board (a Pi 500+ via RP1 xhci is
on the list), what worked, kernel/userland SHAs.</p>
<hr />
<h4>8. Open questions</h4>
<ol>
<li><strong>Kernel size delta</strong> — measure in K1 (<code>size /boot/kernel/kernel</code> before/after) rather than trusting §1.3's estimate.</li>
<li><strong>Are the BT userland tools really on the image?</strong> Expected yes (§2) but unverified; K1's acceptance settles it.</li>
<li><strong>Firmware set size</strong> for Intel <code>ibt-*</code> — measure in K3; if it is tens of MB, consider trimming to the ids <code>ng_ubt_intel.c</code> lists (the tool picks by <code>hw_variant</code>/<code>hw_revision</code>, so the mapping is derivable from <code>iwmbtfw</code>'s source).</li>
<li><strong>Who runs the firmware loaders</strong> — §3.6 argues <code>bluetoothd</code>; if area 2 prefers a separate <code>org.nextbsd.btfw</code> one-shot, K4's contract still holds.</li>
<li><strong>Pi firmware state</strong> of gio 29 / uart0 pinmux / uarta clock — K7 measures; changes K8's scope.</li>
<li><strong>IOUSBDevice matching in the catalogue</strong> — not needed for E16; worth a K-series ticket later so USB drivers can be kexts.</li>
<li><strong>Broadcom patchram for USB parts</strong> (BCM20702 on Macs) — ROM firmware works; a <code>.hcd</code> loader over <code>ugen</code> (~300 LOC, same shape as <code>iwmbtfw</code>) would be a Harden item if Mac users hit ROM bugs.</li>
<li><strong>BLE</strong> — the stack supports LE HCI commands (<code>hccontrol</code> has an <code>le_commands</code> table, <code>hccontrol.c:190</code>) but no LE L2CAP/ATT/SMP; that is the seed ticket's "classic first" question, not a kernel-config one.</li>
</ol>
<h4>9. Risks</h4>
<ul>
<li><strong>Silent failure class (kernel#52).</strong> If any of the seven options is dropped in a future config edit, the symptom is <code>hccontrol: Could not create socket</code> or <code>ngctl: send msg: No such file or directory</code>, not a kernel message. K2's boot-test assertions are the guard.</li>
<li><strong>Intel bootloader lock-up.</strong> Attaching the stack to an Intel part in bootloader mode hard-locks it until power-cycle (<code>ng_ubt_intel.c:33-37</code>). <code>ng_ubt_intel</code> prevents this, and it is inside the same <code>NETGRAPH_BLUETOOTH_UBT</code> token, so it cannot be forgotten — but a future "generic class E0" kext or a hand <code>mkpeer</code> on the wrong node could still do it.</li>
<li><strong>Firmware licence hygiene.</strong> Intel/Realtek/Cypress blobs must ship with their <code>copyright</code>/EULA text; the DTB precedent (<code>build.sh:480-482</code>) shows how.</li>
<li><strong>Hardware coverage.</strong> Until K6 runs on real dongles, everything above the USB enumeration is reasoned from source. Same honesty clause as the WLAN plan.</li>
<li><strong>Pi 5 expectations.</strong> The onboard radio being parked must be visible in the epic, or "Bluetooth on the Pi 500" will be read as promised.</li>
</ul>
<h4>10. Ticket index (see <code>1-kernel-hardware-tickets.json</code>)</h4>
<table>
<thead>
<tr>
<th>ID</th>
<th>Repo</th>
<th>Title</th>
<th>Track</th>
<th>Size</th>
</tr>
</thead>
<tbody>
<tr>
<td>K1</td>
<td>nextbsd-kernel</td>
<td>config: bake netgraph + the Bluetooth stack (ng_bluetooth/hci/l2cap/btsocket/ubt) into NEXTBSD — no .ko tree, so nothing can autoload (#412 phase 0)</td>
<td>Ship</td>
<td>S</td>
</tr>
<tr>
<td>K2</td>
<td>nextbsd</td>
<td>boot-test: assert the Bluetooth stack is present on both arches (ngctl list/types, net.bluetooth, hccontrol exits 7) and guard the kernel options</td>
<td>Ship</td>
<td>S</td>
</tr>
<tr>
<td>K3</td>
<td>nextbsd</td>
<td>Ship Intel (ibt-*) and Realtek (rtl_bt) Bluetooth firmware in the image, with licences — fetched at assembly like the Pi DTBs</td>
<td>Ship</td>
<td>S</td>
</tr>
<tr>
<td>K4</td>
<td>nextbsd-userland</td>
<td>Contract: bluetoothd runs iwmbtfw/rtlbtfw on USB arrival for controllers that boot in bootloader/ROM mode (devd's iwmbtfw.conf/rtlbtfw.conf without devd)</td>
<td>Sequence</td>
<td>M</td>
</tr>
<tr>
<td>K5</td>
<td>nextbsd-userland</td>
<td>btemu: a userland HCI controller on ng_hci's drv hook so CI can exercise hci/l2cap/btsocket and bluetoothd without a radio</td>
<td>Harden</td>
<td>M</td>
</tr>
<tr>
<td>K6</td>
<td>nextbsd</td>
<td>Phase 1: hand-verify the baked stack on real USB dongles (amd64 + Pi 500+ via RP1 xhci) and start the Bluetooth hardware matrix</td>
<td>Ship</td>
<td>S</td>
</tr>
<tr>
<td>K7</td>
<td>nextbsd-kernel</td>
<td>rpi5: measure what the firmware leaves for the onboard CYW43455 Bluetooth (BT_ON gio 29, uarta pinmux, 96 MHz clock, bdaddr) before any driver work</td>
<td>Needs answer</td>
<td>S</td>
</tr>
<tr>
<td>K8</td>
<td>nextbsd-kernel</td>
<td>rpi5: onboard Bluetooth over uarta — bcm7271 UART compat, brcmstb-gpio, bcm2712-pinctrl, an H4 transport on ttyhook, BCM4345C0.hcd patchram (parked)</td>
<td>Parked</td>
<td>XL</td>
</tr>
</tbody>
</table>
<h2 id="area2">Engine & Classic vs BLE (B)</h2>
<p style="font-size:.85rem;color:var(--muted)">Deep-dive notes, lightly edited. Draft ids map to issues in the <a href="#index">index</a>.</p>
<p>Research for nextbsd/nextbsd#473 (E16 Bluetooth), seed nextbsd/nextbsd#412. Read-only; nothing filed.
All FreeBSD file:line cites are against <code>releng/15.1</code> at <code>88e7371d9dc26f85dfc1b008cbe59ebc7e4a33da</code> (2026-08-24, "Add UPDATING entries and bump version"), sparse-cloned to <code>freebsd-src</code>.</p>
<h4>TL;DR</h4>
<ol>
<li><strong>The plans-site page is wrong on the central fact.</strong> <code>site/freebsd-bluetooth-management.html</code> §4–5 says FreeBSD's stack "supports Classic Bluetooth only — no BLE, no GATT, no SMP" and that "the gap is in the kernel". It is not. Since Takanori Watanabe's 2015 commits (<code>fbc48c2bfb</code> "Initial Bluetooth LE support", <code>3a601a2381</code> "Bluetooth LE Security Management channel support") the kernel does LE HCI, LE ACL connections, and exposes the <strong>ATT (CID 4) and SMP (CID 6) fixed channels as ordinary <code>AF_BLUETOOTH</code> L2CAP sockets</strong> with an LE address type in <code>sockaddr_l2cap</code>. What is missing is entirely <strong>userland</strong>: there is no GATT client, no SMP pairing agent, no LTK store, no HOGP driver in base. Those exist as an out-of-tree prototype (<code>takawata/FreeBSD-BLE</code>, HOGP mouse working; <code>rhaberkorn/FreeBSD-BLE</code> 2025 fork adds a one-shot HID pairing script) with <strong>no license file</strong>.</li>
<li><strong>Classic-first is still right, but for a different reason than "FreeBSD can't do LE".</strong> Classic covers every headset (A2DP/HFP are BR/EDR; LE Audio is not on Apple and is still a minority of shipping headsets), Apple's Magic Keyboard/Mouse/Trackpad (BR/EDR HID), and the older/cheaper keyboard population. It does <strong>not</strong> cover the Logitech MX line, Microsoft Surface keyboards, Keychron, or essentially any mouse/keyboard designed after ~2018 — those are LE-only (HOGP). So "Classic first" ships headsets + Apple peripherals; <strong>LE HID is the second milestone, not a someday</strong>, and the engine interface must be written for both from day one.</li>
<li><strong>Engine recommendation:</strong> Classic engine = netgraph kernel stack driven directly by <code>bluetoothd</code> over the raw HCI socket (absorbing <code>hcsecd</code>'s three-event loop and adding SSP, which the kernel now passes through since <code>4ae0fa8a2f</code>, 2025-01). LE engine = a small <strong>userland ATT/GATT/SMP host over the kernel's ATT/SMP sockets</strong> — the FreeBSD-BLE shape, clean-room or relicensed — <em>not</em> a full third-party host. NimBLE/BTstack-style full hosts need the raw ACL stream, which on netgraph means taking ng_hci's single <code>acl</code> hook away from <code>ng_l2cap</code> and killing Classic (BTstack's own FreeBSD port documents exactly this). BlueZ stays out. A NimBLE spike is worth one ticket only to price the "tee node" alternative; the default is the thin host.</li>
<li>Kernel LE gaps that matter are small and fixable in <code>nextbsd-kernel</code>: LE buffer accounting ignores <code>LE_Read_Buffer_Size</code>; <code>LE_Connection_Update_Complete</code>, <code>LE_Read_Remote_Features</code>, <code>LE_Enhanced_Connection_Complete</code> are stubs; LE signalling accepts parameter-update requests but never forwards them to the controller; LE CoC (dynamic LE channels) unsupported. None block HOGP.</li>
</ol>
<hr />
<h4>1. Exact state of FreeBSD 15.1's stack</h4>
<h5>1.1 What exists (LE), with cites</h5>
<table>
<thead>
<tr>
<th>Layer</th>
<th>Present in 15.1</th>
<th>Evidence</th>
</tr>
</thead>
<tbody>
<tr>
<td>HCI LE command group (OGF 0x08)</td>
<td>All Core 4.0 LE commands + data-length + buffer-size v2 defined; kernel post-processes Command_Complete / Command_Status for them</td>
<td><code>sys/netgraph/bluetooth/include/ng_hci.h:1587-1848</code> (OCFs 0x01–0x1f, 0x23, 0x24, 0x60); <code>hci/ng_hci_cmds.c:817-876</code> <code>process_le_params</code>, <code>:877-916</code> <code>process_le_status</code></td>
</tr>
<tr>
<td>LE Meta event (0x3e)</td>
<td>Dispatched. Handled: <code>LE_Connection_Complete</code> (0x01), <code>LE_Advertising_Report</code> (0x02), <code>LE_Connection_Update_Complete</code> (0x03, body is <code>/*TBD*/</code>). <strong>Not handled</strong> (freed): <code>LE_Read_Remote_Features_Complete</code> (0x04), <code>LE_Long_Term_Key_Request</code> (0x05), everything else. Every event is still <strong>mirrored to the raw hook before the switch</strong> (<code>ng_hci_mtap</code>, <code>hci/ng_hci_main.c:719</code>, <code>hci/ng_hci_misc.c:63-78</code>), so userland sees LTK requests etc.</td>
<td><code>hci/ng_hci_evnt.c:129</code> (<code>case NG_HCI_EVENT_LE</code>), <code>:376-620</code> (<code>le_event</code>, <code>le_advertizing_report</code>, <code>le_connection_complete</code>, <code>le_connection_update</code>)</td>
</tr>
<tr>
<td>LE connections (central)</td>
<td><code>LP_CON_REQ</code> with link type <code>NG_HCI_LINK_LE_PUBLIC</code>/<code>_RANDOM</code> emits <code>LE_Create_Connection</code>; connection descriptor created on <code>LE_Connection_Complete</code>; peripheral-role (incoming) connection also creates a descriptor and sends <code>LP_CON_IND</code> up</td>
<td><code>hci/ng_hci_ulpi.c:107-109</code>, <code>:486-623</code> (<code>ng_hci_lp_le_con_req</code>); <code>hci/ng_hci_evnt.c:471-569</code></td>
</tr>
<tr>
<td>LE address types</td>
<td><code>NG_HCI_LINK_LE_PUBLIC</code> 0x02 / <code>NG_HCI_LINK_LE_RANDOM</code> 0x03; userland <code>BDADDR_BREDR</code> 0 / <code>BDADDR_LE_PUBLIC</code> 1 / <code>BDADDR_LE_RANDOM</code></td>
<td><code>include/ng_hci.h:123-124</code>; <code>include/ng_bluetooth.h:228-229</code>; <code>hci/ng_hci_main.c:102-105</code></td>
</tr>
<tr>
<td>LE advertising cache</td>
<td>Advertising reports populate the neighbor cache with <code>addrtype</code>, AD payload (<code>extinq_data</code>, up to 240 B) and RSSI (stored in <code>page_scan_mode</code>); exported to userland via the neighbor-cache ioctl (<code>4aa92fe2f3</code>, 2017)</td>
<td><code>hci/ng_hci_evnt.c:379-469</code>; <code>include/ng_hci.h:632-634</code></td>
</tr>
<tr>
<td>L2CAP LE fixed channels</td>
<td>CIDs defined: ATT 0x04, LE-signal 0x05, SMP 0x06; ATT/SMP channels are auto-created per LE connection and opened/closed with it; <code>NG_L2CAP_MTU_LE_MINIMAM 23</code></td>
<td><code>include/ng_l2cap.h:75-87</code>, <code>:359-361</code> (<code>IDTYPE_ATT/LE/SMP</code>); <code>l2cap/ng_l2cap_misc.c:343-345</code>; <code>l2cap/ng_l2cap_ulpi.c:131-136,196-199,245-246,872-875,1006-1020</code></td>
</tr>
<tr>
<td>L2CAP LE signalling (CID 5)</td>
<td>Parses <code>Connection_Parameter_Update_Request/Response</code>; <strong>always replies ACCEPT but never issues <code>LE_Connection_Update</code> to the controller</strong> (<code>/*TBD.*/</code>)</td>
<td><code>l2cap/ng_l2cap_evnt.c:134-136,278-372</code> (<code>send_l2cap_param_urs(..., ACCEPT)</code> at <code>:363</code>); <code>l2cap/ng_l2cap_cmds.c:224-226</code></td>
</tr>
<tr>
<td>L2CAP LE CoC (dynamic LE channels, PSM-based)</td>
<td><strong>Not supported</strong>: <code>connect()</code> with LE addr type and <code>l2cap_cid == 0</code> returns <code>EINVAL</code> (<code>// Not supported yet</code>)</td>
<td><code>socket/ng_btsocket_l2cap.c:2183-2192</code></td>
</tr>
<tr>
<td>Socket API</td>
<td><code>struct sockaddr_l2cap</code> gained <code>l2cap_cid</code> and <code>l2cap_bdaddr_type</code> (with a compat struct); <code>connect()</code>/<code>bind()</code> to <code>{bdaddr, type=LE_*, cid=ATT_CID or SMP_CID}</code> gives a SEQPACKET socket on the fixed channel; <code>SO_L2CAP_ENCRYPTED</code> makes the connect wait for encryption; encryption-change events update the socket; LE socket is torn down when the HCI connection drops (<code>b32073c458</code>, 2016)</td>
<td><code>include/ng_btsocket.h:225-247</code>; <code>socket/ng_btsocket_l2cap.c:228-231,465-483,690-720,2366-2372,2533-2537</code></td>
</tr>
<tr>
<td>Raw HCI socket</td>
<td>Root sockets bypass the security filter and may send any opcode incl. all of OGF LE; per-socket packet/event filter; commands only (<strong>ACL data cannot be injected</strong>: <code>ng_hci_raw_rcvdata</code> drops anything but <code>NG_HCI_CMD_PKT</code>) but <strong>outbound and inbound ACL are mirrored</strong> to raw for sniffing</td>
<td><code>socket/ng_btsocket_hci_raw.c:676-724,878,937</code>; <code>hci/ng_hci_main.c:1025-1102</code>; <code>hci/ng_hci_evnt.c:319</code>, <code>hci/ng_hci_main.c:719</code></td>
</tr>
<tr>
<td>Classic SSP plumbing</td>
<td><code>IO_Capability_Request</code> (0x31), <code>Simple_Pairing_Complete</code> (0x36) events and the IO-cap / user-confirmation reply OCFs (0x2b–0x2d, 0x34) defined; kernel passes the events through untouched to raw (commit <code>4ae0fa8a2f</code>, 2025-01-27, PR 265066, FreeBSD Foundation). <strong><code>hcsecd</code> does not use them</strong> — it filters only <code>PIN_CODE_REQ</code>, <code>LINK_KEY_REQ</code>, <code>LINK_KEY_NOTIFICATION</code></td>
<td><code>include/ng_hci.h:865-898,2089-2094</code>; <code>hci/ng_hci_evnt.c:123-124</code>; <code>usr.sbin/bluetooth/hcsecd/hcsecd.c:123-126</code></td>
</tr>
<tr>
<td>hccontrol LE</td>
<td>20 <code>le_*</code> subcommands: <code>le_enable</code>, scan/advertise params & data, whitelist, <code>le_connect -a addr -t public|random</code>, <code>le_read_buffer_size</code>, channel map, remote features, <code>le_rand</code>; generic AD-data builder <code>adv_data.c</code> (<code>2c6feab253</code>, 2026-03)</td>
<td><code>usr.sbin/bluetooth/hccontrol/le.c:1240-1365</code>, <code>adv_data.c</code></td>
</tr>
<tr>
<td>Controllers</td>
<td><code>ng_ubt</code> + Intel (<code>iwmbtfw</code>, AX200/AX210/AX411/BE200 as of <code>d82bcf5681</code> 2026-03) and Realtek (<code>rtlbtfw</code>, 8852CE <code>2e93669827</code> 2026-03) firmware loaders; all dual-mode</td>
<td><code>sys/netgraph/bluetooth/drivers/ubt/</code>, <code>usr.sbin/bluetooth/{iwmbtfw,rtlbtfw}</code></td>
</tr>
</tbody>
</table>
<p>Commit trail (all <code>git log</code> via <code>gh api repos/freebsd/freebsd-src/commits?path=…&sha=releng/15.1</code>): <code>bcff2d9100</code> 2015-04-18 hccontrol LE commands; <code>fbc48c2bfb</code> 2015-04-07 kernel initial LE; <code>3a601a2381</code> 2015-10-27 SMP channel; <code>483ed39512</code> 2015-11-07 encryption error handling; <code>b32073c458</code> 2016-06-07 LE socket teardown; <code>4aa92fe2f3</code> 2017-04-27 AD cache to userland; 2020-04..07 hselasky/takawata hccontrol <code>le_scan</code>, <code>le_connect</code>, whitelist, advertising; <code>4ae0fa8a2f</code> 2025-01-27 SSP events; <code>2c6feab253</code> 2026-03-18 generic AdvData. Nothing LE-related landed on <code>main</code> between 2025-06 and 2026-09 beyond that (checked <code>sys/netgraph/bluetooth</code> and <code>usr.sbin/bluetooth</code> paths).</p>
<h5>1.2 What is missing (precisely)</h5>
<p>Kernel (<code>nextbsd-kernel</code>, all small):</p>
<ul>
<li><strong>LE buffer accounting.</strong> <code>LE_Read_Buffer_Size</code> is in the "no post processing" list (<code>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:412</code> area, <code>NG_HCI_BUFF_ACL_TOTAL</code>). Controllers with a separate, smaller LE pool can be over-driven; controllers reporting LE buffer size 0 (shared pool) are fine. Not observed as a bug in FreeBSD-BLE use (HID traffic is tiny) — <strong>unverified risk</strong>, worth a targeted fix.</li>
<li><strong>Stub LE meta handlers:</strong> <code>LE_Connection_Update_Complete</code> (<code>ng_hci_evnt.c:571-578</code> TBD), <code>LE_Read_Remote_Features_Complete</code>, <code>LE_Long_Term_Key_Request</code> (<code>:602-606</code>, both <code>//TBD</code> fallthrough to free). Peripheral-role LTK reply therefore must come from userland via raw HCI (the event is mirrored there). <code>LE_Enhanced_Connection_Complete</code> (0x0a) is defined but not handled — so userland must <strong>not</strong> enable it in the LE event mask, or connections never register in the kernel.</li>
<li><strong>LE signalling:</strong> parameter-update requests are accepted but never forwarded as <code>LE_Connection_Update</code> (<code>ng_l2cap_cmds.c:224-226</code> TBD). HOGP mice that ask for a faster interval get an ACK and no change — functional, higher latency. (<code>rhaberkorn</code> fork commit <code>6b146e2aae</code> "commented-out connection update for optimized latency" is userland working around this via raw HCI.)</li>
<li><strong>LE CoC</strong> (<code>ng_btsocket_l2cap.c:2188-2190</code>) — not needed for HID; needed for some modern GATT-over-CoC/EATT devices only.</li>
<li>No extended advertising / 2M-coded PHY / periodic adv OCFs in <code>ng_hci.h</code> (0x20+, 0x36+ absent). Root raw sockets can still send them (the security filter only gates unprivileged sockets, <code>ng_btsocket_hci_raw.c:684-715</code>), but <code>process_le_params</code> returns <code>EINVAL</code> for unknown OCFs (<code>:857-866</code>), which just logs — <strong>unverified</strong> whether the error path drops the command-complete from the raw mirror; needs a test.</li>
<li>ISO channels / LE Audio: nothing.</li>
</ul>
<p>Userland (base has none of this):</p>
<ul>
<li>GATT client (service/characteristic discovery, read/write/notify), ATT MTU exchange.</li>
<li>SMP pairing agent (legacy LE pairing incl. Just-Works/Passkey; LE Secure Connections needs P-256 ECDH — do it in userland with libcrypto; the controller P-256 OCFs 0x25/0x26 are not in <code>ng_hci.h</code>).</li>
<li>LTK/IRK/CSRK bond store, and the peripheral-role responder for <code>LE_Long_Term_Key_Request</code> → <code>LE_Long_Term_Key_Request_Reply</code> (defined, <code>ng_hci.h:1778</code>).</li>
<li>HOGP (HID over GATT) → <code>uhid</code>/evdev bridge (<code>bthidd</code> is Classic only: <code>bthidd/{client,server}.c</code> hardcode <code>BDADDR_BREDR</code>, <code>l2cap_cid = 0</code>).</li>
<li>Advertising-data parsing for the scan UI (kernel gives raw AD bytes).</li>
<li>Random/resolvable-address handling (IRK resolution).</li>
</ul>
<p>All of that is what <code>takawata/FreeBSD-BLE</code> implements: <code>le_enable</code> (scan, connect ATT, dump attributes, ~23 KB C), <code>lepair</code> (SMP legacy pairing, prints EDIV/Rand/LTK, ~12 KB), <code>lesecd</code> (hcsecd-shaped LTK responder daemon, ~12 KB + yacc/lex config), <code>lehid</code> (GATT client with HOGP mouse via uinput, battery, HRP, MIDI… ~100 KB of small service drivers). README: "Kernel support was already committed to main trunk." Last upstream push 2023-05-01; <code>rhaberkorn</code> fork (<code>improvements</code> branch, 2025-01) adds HOGP heuristics, mouse events via uevent, random addresses, and <code>hid-pair.sh</code>. <strong>License: none in either repo</strong> (GitHub reports no license; all rights reserved by default). The FreeBSD forum thread "The current state of BT-LE?" (2024-11 → 2025-02) shows it being used against an MX Master 3S with ATT timeouts on that device — i.e. a prototype, not a product.</p>
<h5>1.3 Classic state (for completeness)</h5>
<p>Complete for HID/A2DP-transport/RFCOMM/SDP: <code>ng_l2cap</code>, <code>ng_btsocket_{l2cap,rfcomm,sco,hci_raw}</code>, <code>sdpd</code>, <code>bthidd</code> (kbd + mouse → <code>uinput</code>/<code>vkbd</code>), <code>btpand</code>, <code>rfcomm_pppd</code>, <code>hcsecd</code>. Pairing is <strong>legacy PIN only</strong> in <code>hcsecd</code>; a device that insists on SSP/Secure Connections Only will not pair until a daemon answers <code>IO_Capability_Request</code> and <code>User_Confirmation_Request</code> over the raw socket — which the kernel now permits. No A2DP/AVRCP/HFP codec or audio path in base (area A).</p>
<hr />
<h4>2. Permissively licensed LE host stacks — comparison</h4>
<p>Evaluated for: running in NextBSD userland, over what transport, coexisting with kernel Classic on the same controller.</p>
<table>
<thead>
<tr>
<th>Stack</th>
<th>License</th>
<th>Language / size</th>
<th>Classic</th>
<th>OS abstraction needed</th>
<th>Transport it wants</th>
<th>Fit on netgraph</th>
<th>Verdict</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Kernel + thin userland host</strong> (FreeBSD-BLE shape)</td>
<td>Kernel BSD-2; userland ours (or relicensed FreeBSD-BLE)</td>
<td>C; ~30–40 KB for ATT/GATT/SMP core + HOGP</td>
<td>Coexists (kernel L2CAP stays)</td>
<td>None — plain sockets + raw HCI</td>
<td><code>AF_BLUETOOTH</code> L2CAP sockets on CID 4/6 + raw HCI for GAP</td>
<td><strong>Native</strong></td>
<td><strong>Recommended LE engine</strong></td>
</tr>
<tr>
<td><strong>Apache NimBLE host</strong></td>
<td>Apache-2.0</td>
<td>C; <code>nimble/host/src</code> 46 files, ~1.2 MB source; Bluetooth 5.4, LE-only ("Host runs on any board and architecture")</td>
<td><strong>No BR/EDR</strong></td>
<td>NPL (<code>porting/npl/linux</code>: pthread mutex/sem/eventq/callout/task, ~20 KB) — trivially compiles on FreeBSD</td>
<td>Raw H4 stream: HCI cmd/evt <strong>and ACL data</strong>. Linux port uses <code>AF_BLUETOOTH</code> <code>HCI_CHANNEL_USER</code>/<code>RAW</code> (<code>nimble/transport/socket/src/ble_hci_socket.c:54-62,672-747</code>)</td>
<td><strong>Bad by default</strong>: netgraph raw socket cannot inject ACL (<code>ng_hci_raw_rcvdata</code> rejects non-CMD). Needs a custom <code>ng_socket</code> on ng_hci's <code>acl</code> hook, which is a single hook (<code>ng_hci_main.c:205-206</code>) — displacing <code>ng_l2cap</code> and all Classic. Fix would be a new tee node routing LE conn-handles to userland (see B7).</td>
<td>Spike only</td>
</tr>
<tr>
<td><strong>Zephyr Bluetooth host</strong></td>
<td>Apache-2.0</td>
<td>C, large; LE + partial Classic (BR/EDR is experimental)</td>
<td>Partial</td>
<td>Deeply tied to Zephyr kernel (<code>k_work</code>, <code>net_buf</code>, <code>k_fifo</code>, Kconfig, devicetree). No standalone port; <code>native_sim</code> runs Zephyr-the-RTOS on POSIX, not the host as a library</td>
<td>H4/H5/USB via Zephyr drivers</td>
<td>Would need the Zephyr kernel emulation layer — far more OS glue than NimBLE, for no gain</td>
<td>No</td>
</tr>
<tr>
<td><strong>BTstack</strong> (BlueKitchen)</td>
<td>BSD-3 + clause 4 "solely for personal benefit and not for any commercial purpose"; commercial licence by quote</td>
<td>C; dual-mode, mature, qualified</td>
<td><strong>Yes</strong> (A2DP, HFP, HID, plus LE GATT/SMP)</td>
<td>Own run loop; POSIX port exists</td>
<td><strong>Has a FreeBSD netgraph port</strong> (<code>port/freebsd-netgraph/</code>, active 2025-26): creates an <code>ng_socket</code> on ng_hci's <code>acl</code> and <code>raw</code> hooks — README: "The OS Bluetooth functionality will be interrupted"</td>
<td>Proves the full-host-on-netgraph pattern and its cost</td>
<td>Licence excludes it from an OS base; useful as a <strong>reference</strong> for the ng_socket transport</td>
</tr>
<tr>
<td><strong>Google Bumble</strong></td>
<td>Apache-2.0</td>
<td>Python; LE + Classic incl. A2DP, HFP, HID, SDP, RFCOMM</td>
<td>Yes</td>
<td>asyncio; HCI over USB (pyusb), UART, VHCI</td>
<td>Raw H4 (owns the controller)</td>
<td>Same acl-hook problem; Python in a system daemon path is a non-starter</td>
<td>Excellent <strong>test/dev tool</strong> (virtual peers, protocol fuzzing), not an engine</td>
</tr>
<tr>
<td><strong>Android Fluoride / GD</strong></td>
<td>Apache-2.0</td>
<td>C++/Rust, very large (AOSP <code>packages/modules/Bluetooth</code>), Android-only build, binder</td>
<td>Yes</td>
<td>Enormous</td>
<td>Raw H4 / vendor HAL</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td><strong>NetBSD netbt</strong></td>
<td>BSD-2</td>
<td>C kernel; Classic only. LE: <code>sys/netbt/hci_le.h</code> (368 lines of defines, commit <code>ace5c075a2</code> 2024-03-13 "Bluetooth low energy - A beginning at least… I have not as yet completed") — no LE code in <code>hci_event.c</code></td>
<td>Yes</td>
<td>n/a</td>
<td>n/a</td>
<td>Behind FreeBSD; nothing to take</td>
<td>No</td>
</tr>
<tr>
<td><strong>OpenBSD</strong></td>
<td>—</td>
<td>Removed Bluetooth from the tree in 2014</td>
<td>—</td>
<td>—</td>
<td>—</td>
<td>—</td>
<td>No</td>
</tr>
<tr>
<td><strong>Direct-BT</strong> (jausoft)</td>
<td>MIT</td>
<td>C++; LE-centric, over Linux HCI + L2CAP sockets + SMP interception</td>
<td>Little</td>
<td>Linux-socket coupled; FreeBSD forum thread (2025-09 → 2026-01) discussed porting using FreeBSD-BLE as reference; no port exists</td>
<td>Kernel L2CAP sockets (same shape as ours!)</td>
<td>Conceptually compatible but C++/GPL-ish history (MIT now), heavy</td>
<td>No, but its design validates the thin-host-over-kernel-L2CAP approach</td>
</tr>
<tr>
<td><strong>BlueZ</strong></td>
<td>GPL-2 / LGPL</td>
<td>—</td>
<td>—</td>
<td>Linux kernel BT subsystem, D-Bus</td>
<td>—</td>
<td>Out (agreed)</td>
<td>No</td>
</tr>
</tbody>
</table>
<p>Coexistence rule, from the code: <strong>anything that needs to send LE ACL data must go through <code>ng_l2cap</code></strong>, because ng_hci has exactly one <code>acl</code> hook and the raw hook is command-only. <code>ng_l2cap</code> already provides exactly the two LE fixed channels a GATT/SMP host needs, as sockets, with per-socket encryption state. So the thin host is not a compromise — it is the design the kernel was built for, and it coexists with Classic by construction: the same raw HCI socket, with different event filters (<code>SO_HCI_RAW_FILTER</code>), serves inquiry + SSP for Classic and scan + LTK for LE, and one daemon owns both.</p>
<hr />
<h4>3. Market reality — what users bring</h4>
<table>
<thead>
<tr>
<th>Device class</th>
<th>Radio</th>
<th>Evidence</th>
</tr>
</thead>
<tbody>
<tr>
<td>Logitech MX Master 3S (Bluetooth Edition), MX Keys, MX Anywhere 3</td>
<td><strong>BLE only</strong> ("Connection Type: Bluetooth Low Energy"; Logitech's own "Check for Bluetooth Low Energy Support" article; Logi Bolt otherwise)</td>
<td>support.logi.com spec page 31605553413783; hub.sync.logitech.com "Check for Bluetooth Low Energy Support"</td>
</tr>
<tr>
<td>Microsoft Surface Keyboard / Designer line</td>
<td>BLE 4.0/4.1 (nRF51822)</td>
<td>microsoft.com Surface Keyboard page; teardown notes</td>
</tr>
<tr>
<td>Keychron K-series</td>
<td>Bluetooth 5.1 (BLE; nRF-class SoC)</td>
<td>keychron.com K2 spec</td>
</tr>
<tr>
<td>Apple Magic Keyboard / Magic Mouse 2 / Magic Trackpad 2</td>
<td><strong>Classic BR/EDR HID</strong> (pairs via inquiry; Linux <code>hid-magicmouse</code>/<code>hid-apple</code> over BlueZ HIDP; the recurring Linux fix is <code>UserspaceHID=false</code>)</td>
<td>Linux Mint forum t=471463 / t=387452; kernel <code>hid-magicmouse</code></td>
</tr>
<tr>
<td>Headsets, speakers, AirPods</td>
<td><strong>Classic A2DP/HFP/AVRCP</strong>; LE Audio (LC3/Auracast) is shipping on some Android-first earbuds but "Apple does not support LE Audio as of early 2026", and every LE Audio headset still carries Classic for fallback</td>
<td>avantree LE Audio list; bluetooth.com LE Audio; alphonsolabs 2026 checklist</td>
</tr>
<tr>
<td>Game controllers (DualShock 4, Xbox pre-2021)</td>
<td>Classic</td>
<td>(general knowledge, unverified here)</td>
</tr>
<tr>
<td>Watches, trackers, sensors, phones' Continuity</td>
<td>BLE / GATT</td>
<td>plans-site §7</td>
</tr>
</tbody>
</table>
<p>Reading: <strong>Classic covers audio and Apple input; LE covers nearly every third-party keyboard/mouse sold since ~2018.</strong> A desktop user with an MX Master and a Keychron gets nothing from a Classic-only stack; a user with AirPods and a Magic Keyboard gets everything. Neither half is optional for "a desktop", but Classic first is correct because (a) its kernel path is complete and battle-tested, (b) <code>bthidd</code> exists, (c) it is where pairing UX (PIN/SSP) and the bond store get designed once, and (d) LE's userland is the same daemon plus one more engine module, not a new architecture.</p>
<hr />
<h4>4. Recommendation</h4>
<h5>4.1 Decision</h5>
<p><strong>Classic-first on netgraph, LE second on the same daemon via a thin userland ATT/GATT/SMP host over the kernel's LE fixed-channel sockets.</strong> Concretely:</p>
<ol>
<li><code>bluetoothd</code> owns the raw HCI socket per adapter (root; privileged filter bypass). It absorbs <code>hcsecd</code> (three events → link-key file) and adds SSP (IO-cap reply "DisplayYesNo"/"KeyboardOnly"/"NoInputNoOutput" per UI availability, numeric comparison, passkey entry) — the kernel now forwards those events. This is engine work, not a wrapper: <code>hcsecd</code> is 500 lines and has no SSP; supervising it buys nothing (unlike <code>wpa_supplicant</code>, which is 300 k lines).</li>
<li><code>sdpd</code> and <code>bthidd</code> are <strong>supervised</strong> as launchd jobs, <code>wpa_supplicant</code>-style, not absorbed; <code>bthidd.conf</code> is generated by <code>bluetoothd</code> from the bond store (area H).</li>
<li>LE engine = new module in <code>bluetoothd</code> (or a <code>libbtle</code> it links): GAP over raw HCI (scan/adv-report parsing, <code>LE_Create_Connection</code> — or let the kernel do it via socket <code>connect()</code> with an LE address type, which is simpler), ATT/GATT client over the CID-4 socket, SMP over the CID-6 socket, LTK responder for <code>LE_Long_Term_Key_Request</code> on raw HCI, <code>LE_Start_Encryption</code> for central role. HOGP → <code>uhid</code>/evdev bridge lives in area H but consumes this engine's GATT API.</li>
<li>Do not vendor a full host. File one spike (B7) to price a <code>ng_btle_tee</code> node that would let NimBLE take LE ACL — only if the thin host stalls on GATT breadth (EATT, CoC, LE Audio).</li>
<li>Engine-neutral <strong>bond record</strong> from day one: <code>{addr, addr_type, kind: BREDR|LE, link_key | {ltk, ediv, rand, irk, csrk, key_size, authenticated, sc}, name, class/appearance, hid: bool}</code> in SCPreferences (WLAN precedent; keychain later).</li>
</ol>
<h5>4.2 Engine interface <code>bluetoothd</code> should code against</h5>
<p>Modelled on <code>ul/src/WLAN/supplicant.h</code> (opaque engine object, fd for the event loop, pump-events returning "state changed", caller-owned caches, no callbacks across threads). One header, two implementations sharing the adapter/raw-HCI plumbing:</p>
<pre><code class="language-c">/* engine.h — what bluetoothd's policy layer sees. Transport-agnostic. */
enum bt_addr_type { BT_ADDR_BREDR, BT_ADDR_LE_PUBLIC, BT_ADDR_LE_RANDOM };
struct bt_addr { uint8_t b[6]; enum bt_addr_type type; }; /* identity, not connection */
struct bt_found { struct bt_addr addr; char name[249]; int rssi;
uint32_t cod; /* Classic class-of-device */
uint16_t appearance; /* LE GAP appearance */
uint8_t ad[240]; uint8_t ad_len; /* raw AD/EIR */
bool bredr, le; }; /* which engines saw it */
enum bt_pair_io { BT_IO_NONE, BT_IO_DISPLAY_YESNO, BT_IO_KEYBOARD, BT_IO_DISPLAY_ONLY };
enum bt_pair_ask { BT_ASK_PIN, BT_ASK_PASSKEY, BT_ASK_CONFIRM, BT_ASK_DISPLAY_PASSKEY };
struct bt_pair_prompt { enum bt_pair_ask kind; uint32_t passkey; }; /* surfaced to CLI/UI */
struct bt_bond { struct bt_addr addr; enum { BOND_BREDR, BOND_LE } kind;
uint8_t link_key[16]; /* Classic */
uint8_t ltk[16], irk[16], csrk[16]; uint16_t ediv; uint64_t rand;
uint8_t key_size; bool authenticated, secure_conn; /* LE */ };
struct bt_engine_ops {
const char *name; /* "classic" | "le" */
int (*attach)(struct bt_adapter *, struct bt_engine **);
void (*detach)(struct bt_engine *);
int (*event_fd)(const struct bt_engine *); /* raw HCI / L2CAP fds for kqueue */
bool (*pump)(struct bt_engine *); /* drain events; true if state changed */
int (*discover)(struct bt_engine *, bool on); /* inquiry+name / LE scan */
int (*found_count)(const struct bt_engine *);
bool (*found_get)(const struct bt_engine *, int i, struct bt_found *);
int (*pair)(struct bt_engine *, const struct bt_addr *, enum bt_pair_io);
int (*pair_reply)(struct bt_engine *, const struct bt_addr *, const char *pin_or_passkey, bool yes);
int (*connect)(struct bt_engine *, const struct bt_addr *);
int (*disconnect)(struct bt_engine *, const struct bt_addr *);
int (*bond_export)(struct bt_engine *, const struct bt_addr *, struct bt_bond *);
int (*bond_import)(struct bt_engine *, const struct bt_bond *); /* at boot, from SCPreferences */
int (*profiles)(struct bt_engine *, const struct bt_addr *, uint16_t *uuids, int max); /* SDP / GATT primary services */
};
/* Events the policy layer consumes (queue drained by pump()): */
enum bt_ev { BT_EV_FOUND, BT_EV_PAIR_PROMPT, BT_EV_PAIRED, BT_EV_PAIR_FAILED,
BT_EV_CONNECTED, BT_EV_DISCONNECTED, BT_EV_BOND_UPDATED };
</code></pre>
<p>Rules that keep the LE engine a drop-in: device identity is <code>bt_addr</code> <strong>with type</strong> everywhere (the CLI shows <code>AA:BB:..:FF/le-random</code>); the bond store is keyed on it; <code>bt_found</code> carries raw AD/EIR so the UI can grow icons/appearance without an interface change; pairing prompts are one shape for PIN, SSP numeric comparison and LE passkey; the dynamic-store publication <code>State:/Bluetooth/Device/<addr></code> uses the same dictionary for both. The Classic engine ships first with <code>profiles()</code> = SDP; the LE engine adds <code>gatt_*</code> calls in a <em>sub-interface</em> (<code>struct bt_le_ops</code> obtained via <code>bt_engine_le(engine)</code>) that area H's HOGP bridge uses — the policy layer never sees GATT.</p>
<h5>4.3 How LE slots in later without rework</h5>
<ul>
<li>Same daemon, same raw socket (a second <code>SO_HCI_RAW_FILTER</code> mask is not even needed — one socket with a union filter and a dispatcher keyed on event code).</li>
<li>Same adapter bring-up sequence gains three commands: <code>Write_LE_Host_Supported(1,0)</code>, <code>LE_Set_Event_Mask</code> (without bit 0x0a), <code>Set_Event_Mask | LE_META</code> (what <code>hccontrol le_enable</code> does, <code>le.c:334-361</code>).</li>
<li>Discovery merges: one <code>bt_found</code> list; Classic inquiry and LE scan can run back-to-back on a dual-mode controller.</li>
<li>Bond store already has the LE fields; <code>bond_import</code> at boot means "keyboard works at the login window" for both.</li>
<li><code>bthidd</code> (Classic HID) and the HOGP bridge both read bonds from <code>bluetoothd</code>; area H decides whether HOGP lands inside <code>bthidd</code> (it has the <code>uinput</code> glue) or a sibling.</li>
</ul>
<hr />
<h4>5. Open questions</h4>
<ol>
<li><strong>Licence of FreeBSD-BLE.</strong> Neither <code>takawata/FreeBSD-BLE</code> nor <code>rhaberkorn/FreeBSD-BLE</code> has a licence file. Ask Takanori Watanabe (FreeBSD committer <code>takawata@</code>) for BSD-2 — the kernel half is already BSD in base, and Hans Petter Selasky contributed PRs to the repo. Otherwise clean-room from the spec; the ATT/GATT/SMP core is ~2–3 kLOC.</li>
<li><strong>Does PR 265066 include an <code>hcsecd</code> SSP patch that never landed?</strong> bugs.freebsd.org is behind an Anubis wall for automated fetch — <strong>unverified</strong>. If a userland SSP patch exists it shortcuts B4.</li>
<li><strong>LE buffer accounting on Intel AX2xx.</strong> Needs <code>hccontrol le_read_buffer_size</code> on real hardware; if the LE pool is separate and smaller than the ACL pool, B5's fix is mandatory before HOGP notifications at 125 Hz.</li>
<li><strong>Which hardware to bless.</strong> Intel AX200/AX210 (needs <code>iwmbtfw</code> at boot — NextBSD has no <code>devd</code>; how is the firmware loader triggered? area K), Realtek 8852, and a CSR 8510 dongle as the reference; Apple Silicon/Broadcom is out.</li>
<li><strong>Address privacy.</strong> LE peripherals using RPAs need IRK resolution in the daemon and <code>LE_Set_Random_Address</code> for our own privacy; MVP uses identity addresses only (rhaberkorn <code>-r</code> shows random works at the socket level).</li>
<li><strong>Does the policy layer expose GATT to apps</strong> (CoreBluetooth-shaped API for Gershwin) in this epic? Recommend no — E16 ships HID/audio; a <code>CBCentralManager</code> face is a later epic on the same engine.</li>
</ol>
<h4>6. Risks</h4>
<ul>
<li><strong>Plans-site page misleads the epic.</strong> §5/§6 of <code>freebsd-bluetooth-management.html</code> frames LE as a kernel project ("extend Netgraph… large kernel+userland effort"). If tickets are cut from that page, weeks go into re-implementing what <code>ng_l2cap</code> already does. Fix the page (B8).</li>
<li><strong>Classic pairing without SSP is a growing failure mode.</strong> Devices with "Secure Connections Only" or no legacy-PIN fallback will refuse <code>hcsecd</code>-style PIN pairing. SSP in <code>bluetoothd</code> is Ship-track, not Harden.</li>
<li><strong>Prototype-grade LE userland.</strong> FreeBSD-BLE has known ATT timeouts against at least one MX Master 3S (forum, 2025-02); expect device-specific GATT quirks (MTU exchange ordering, <code>Read_By_Group_Type</code> responses, notifications before CCCD write). Budget a hardware-in-the-loop soak.</li>
<li><strong>Kernel LE code is 2015-era and lightly exercised</strong> (<code>le_connection_update</code> TBD, error paths). NextBSD bakes it into the kernel, so a panic in <code>ng_l2cap</code>'s LE paths (note the <code>panic()</code> default in <code>ng_l2cap_con_wakeup</code>, <code>ng_l2cap_cmds.c:228-232</code>) is a boot-visible failure. Fuzz the LE signalling path with Bumble before enabling by default.</li>
<li><strong>No CI hardware</strong> (as WLAN). Bumble's virtual controller + a VHCI-like path does not exist on FreeBSD; the closest is two USB dongles on one test box.</li>
<li><strong>Key material in SCPreferences</strong> — accepted debt, second consumer for the keychain plan.</li>
</ul>
<h4>7. Sources</h4>
<ul>
<li>FreeBSD releng/15.1 tree (paths above), commit list via <code>gh api repos/freebsd/freebsd-src/commits</code>.</li>
<li>takawata/FreeBSD-BLE: https://github.com/takawata/FreeBSD-BLE (README, tree, commits to 2023-05-01); rhaberkorn fork <code>improvements</code> branch (commits 2025-01-09..18).</li>
<li>BTstack FreeBSD netgraph port: https://github.com/bluekitchen/btstack/tree/master/port/freebsd-netgraph ; licence https://github.com/bluekitchen/btstack/blob/master/LICENSE (clause 4).</li>
<li>NimBLE: https://github.com/apache/mynewt-nimble (README "Bluetooth 5.4 stack… Host runs on any board and architecture"; <code>porting/npl/linux</code>; <code>nimble/transport/socket/src/ble_hci_socket.c</code>).</li>
<li>Zephyr host architecture: https://docs.zephyrproject.org/latest/services/connectivity/bluetooth/bluetooth-arch.html</li>
<li>Bumble: https://github.com/google/bumble (Apache-2.0; LE + Classic incl. A2DP/HFP/HID; HCI over USB/UART/VHCI).</li>
<li>NetBSD: https://github.com/NetBSD/src/tree/trunk/sys/netbt (commit <code>ace5c075a2</code>, 2024-03-13).</li>
<li>FreeBSD forums: "The current state of BT-LE?" (t=95598, 2024-11..2025-02); "Interest in porting Direct-BT" (t=99203, 2025-09..2026-01).</li>
<li>Logitech: https://support.logi.com/hc/en-in/articles/31605553413783-Specification-MX-Master-3S-Bluetooth-Edition ; https://hub.sync.logitech.com/mx-anywhere-3/post/check-for-bluetooth-low-energy-support-600LdKtzhGM1pXD</li>
<li>Microsoft Surface Keyboard: https://www.microsoft.com/en-us/d/surface-keyboard/8r3rqvvflp4k ; Keychron K2: https://www.keychron.com/products/keychron-k2-wireless-mechanical-keyboard</li>
<li>Apple Magic devices on Linux (BR/EDR HID): https://forums.linuxmint.com/viewtopic.php?t=471463</li>
<li>LE Audio adoption: https://www.bluetooth.com/learn-about-bluetooth/feature-enhancements/le-audio/ ; https://www.alphonsolabs.com/bluetooth-le-audio-compatibility-checklist/</li>
<li>NextBSD: <code>ul/src/WLAN/{supplicant.h,wland.h,wlan.defs}</code> (engine-interface template); <code>nextbsd-kernel/config/NEXTBSD</code> (0 netgraph lines, confirming #412).</li>
</ul>
<h2 id="area3">bluetoothd & the bluetooth CLI (D)</h2>
<p style="font-size:.85rem;color:var(--muted)">Deep-dive notes, lightly edited. Draft ids map to issues in the <a href="#index">index</a>.</p>
<p>Scoping notes for nextbsd/nextbsd#473 (E16 Bluetooth), seed nextbsd/nextbsd#412. Read-only research; no issues filed. Written 2026-09-20 against local clones of the NextBSD repos and FreeBSD <code>releng/15.1</code>.</p>
<p>Agreed and not relitigated: <code>/usr/sbin/bluetoothd</code>, job <code>org.nextbsd.bluetoothd</code>, Mach service <code>org.nextbsd.bluetooth</code>, CLI <code>/usr/sbin/bluetooth</code>; C + CoreFoundation below the Mach line; MIG; pure-C MIG client CLI; SCPreferences persistence; SCDynamicStore publishing; supervise stock daemons rather than modify them.</p>
<hr />
<h4>0. TL;DR</h4>
<ol>
<li><strong>wland is a 4.1 kLOC, seven-file daemon</strong> (<code>ul/src/WLAN/</code>, 4119 lines total) with one CF translation unit, one Mach-service thread, one flat MIG <code>.defs</code>, one plist, one build block, and a hand-linked CLI. Copying its file layout one-for-one gives bluetoothd its skeleton for free (§1).</li>
<li><strong>Replace <code>hcsecd</code>; do not supervise it.</strong> Evidence: hcsecd handles exactly three HCI events and logs everything else as an error (<code>hcsecd.c:124-127</code>, <code>:190-193</code>); it only stores a new link key for a device that is <em>already declared in <code>/etc/bluetooth/hcsecd.conf</code></em> (<code>hcsecd.c:392-396</code> calls <code>get_key(.., exact_match=1)</code>), so a device paired at runtime never gets its key saved unless something rewrites the config and SIGHUPs it first; it writes keys to disk only on SIGHUP or exit (<code>hcsecd.c:202</code>, <code>:423</code>); it answers PIN requests from a static file and has no way to ask a user; and it has no Secure Simple Pairing at all. The whole daemon is 448 lines and its reply code (~120 lines) is trivially reimplemented over the same raw HCI socket. Two processes answering <code>Link_Key_Request</code> on the same adapter would race, so "supervise hcsecd" is not even a safe option (§3).</li>
<li><strong>SSP is possible on FreeBSD's kernel but nothing in base exercises it.</strong> The raw HCI hook receives a copy of <em>every</em> event before the kernel processes it (<code>ng_hci_main.c:719</code> → <code>ng_hci_misc.c:63-78</code>), the per-socket event filter is a 64-bit bitmap (<code>ng_btsocket.h:71-74</code>) so the SSP events 0x31/0x33/0x36 pass, and <code>ng_hci.h</code> already defines <code>IO_Capability_Request</code>, <code>User_Confirmation_Request</code>, <code>Simple_Pairing_Complete</code>, the reply opcodes (0x2b/0x2c/0x2d/0x34) and <code>Write_Simple_Pairing_Mode</code> (0x0056). But <code>hccontrol</code> has no SSP command, the kernel never sets the controller event mask, and <code>User_Passkey_Request</code> (0x34) / <code>IO_Capability_Response</code> (0x32) are not defined. bluetoothd must send <code>Set_Event_Mask</code> and <code>Write_Simple_Pairing_Mode</code> itself. First real exercise needs hardware (§3.3).</li>
<li><strong>bluetoothd owns the adapter lifecycle the way wland owns the VAP.</strong> On FreeBSD the netgraph graph (<code>ubt0</code> → <code>ng_hci</code> → <code>ng_l2cap</code> → <code>btsock_*</code>) is built by <code>/etc/rc.d/bluetooth</code> (<code>libexec_rc_rc.d_bluetooth</code>, <code>bluetooth_setup_stack</code>), triggered by devd. NextBSD has neither rc.d nor devd (<code>nextbsd/README.md:31</code>). So <code>bt_devenum()</code> returns nothing until bluetoothd builds the graph itself with <code>libnetgraph</code> (§4).</li>
<li><strong>Nothing in the tree can prompt a logged-in user.</strong> No LaunchAgents, no per-user daemons, no <code>CFUserNotification</code>; the only user-facing mechanism is <code>notify_post</code> (hostnamed) and the CLI. So pairing confirmation is <strong>pull, not push</strong>: bluetoothd parks the pairing in <code>State:/Bluetooth/Pairing/<addr></code> + <code>notify_post</code>, and the CLI (<code>bluetooth pair</code>, <code>bluetooth confirm</code>) is the agent. Gershwin's pane drives the same two verbs via NSTask (§5.3).</li>
<li><strong>Link keys are plaintext in SCPreferences, a second time</strong>, but in a <em>separate</em> prefs file from device metadata, <code>0600</code>, behind one function (<code>bt_keys_save()</code>) so the keychain migration later touches one file and one function. This is WLAN's Q2 decision (<code>airport.h:40-48</code>) with a one-file improvement (§6).</li>
<li><strong>CI without an adapter is a first-class deliverable.</strong> wland today is <em>UNPROBED</em> in the wedge check (<code>wedge-check.sh:153,156</code>) and has no boot-test gate at all. bluetoothd ships with markers (<code>BT-RPC-OK</code>, <code>BT-NOSTACK</code>/<code>BT-NOADAPTER</code>, <code>BT-CLI-OK</code>), a <code>bluetooth status</code> probe in <code>wedge-check.sh</code>, and is automatically covered by <code>daemon-state.sh</code> (§8).</li>
</ol>
<hr />
<h4>1. How wland is actually built (the template)</h4>
<h5>1.1 Files</h5>
<table>
<thead>
<tr>
<th>File</th>
<th>Lines</th>
<th>Role</th>
<th>Bluetooth sibling</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>ul/src/WLAN/wland.c</code></td>
<td>655</td>
<td>main loop, radio table, spawns/reaps wpa_supplicant, adopt-on-timer</td>
<td><code>bluetoothd.c</code></td>
</tr>
<tr>
<td><code>ul/src/WLAN/vap.c/.h</code></td>
<td>249/88</td>
<td>PHY enumeration (<code>net.wlan.devices</code> sysctl), VAP clone/adopt</td>
<td><code>adapter.c/.h</code> (ubt detection, netgraph graph, HCI init)</td>
</tr>
<tr>