Skip to content

Apple's open-source XNU kernel on Android phones: its own loader and drivers, Metal on the Adreno. Runs from RAM; a reboot gives the phone back to Android.

C

tools, docs: the boot-argument catalogue: every argument the kernel, loader and user space read, scanned from the source

shimokufc528a47f40f
diff --git a/configs/boot-args.lst b/configs/boot-args.lst
new file mode 100644
index 0000000..f9641e5
--- /dev/null
+++ b/configs/boot-args.lst
@@ -0,0 +1,304 @@
+adreno k
+adreno_blind k
+adreno_dirty k
+adreno_fine k
+adreno_keep k
+adreno_only k
+adreno_pause k
+adreno_return k
+adreno_skip k
+adreno_speed k
+adreno_stream1 k
+adreno_watch k
+adsp k
+adsp_again k
+adsp_apr_wait k
+adsp_keep k
+adsp_listen k
+adsp_new k
+adsp_pause k
+adsp_return k
+adsp_step k
+adsp_wait k
+apfs_cheap k
+apfs_check k
+apfs_chunk k
+apfs_contents k
+apfs_depth k
+apfs_dev k
+apfs_hash k
+apfs_max k
+apfs_meta_cluster k
+apfs_mnt k
+apfs_par k
+apfs_root_c k
+apfs_root_v k
+apfs_round k
+apfs_skip k
+apfs_sparse k
+apfs_store_len k
+apfs_store_note k
+apfs_store_seed k
+apfs_subtree k
+apfs_threads k
+apfs_ubc_read k
+apfs_volume k
+apfs_volume_at k
+apfs_walkers k
+apfs_write_at k
+apfs_write_byte k
+apfs_write_len k
+apfs_write_path k
+applog k
+applog_name k
+autounlock u
+battery kl
+battery_shared_pa k
+battmgr k
+bootcpu kl
+buttons k
+buttons_steps k
+ca_vbl u
+caenv u
+cam kl
+cam_after k
+cam_fake k
+cam_fake_fps k
+cam_frames k
+cam_gain k
+cam_keep_mb k
+cam_mode k
+cam_pattern k
+cam_sensor k
+cam_settle k
+cam_shutter k
+cam_vblank k
+cc_fade u
+cpufreq k
+cpuload k
+cpumask l
+cpus l
+ddr k
+ddr_rest k
+ddr_vote k
+display_probe k
+epoch k
+fb_beat k
+fb_diff k
+fb_filter k
+fb_hz k
+fb_queue k
+fb_threads k
+fbheight k
+fbscale k
+fbtrace k
+fbwidth k
+gamut l
+gl u
+glblit u
+glcensus u
+glcompile u
+glcopy u
+glenv u
+glfetch u
+glframes u
+glgroup u
+glno u
+glnumbers u
+glplain u
+glprecision u
+glsb3 u
+glshaders u
+glshow u
+glshow_part u
+glshow_zoom u
+glskip u
+glslow u
+glsync u
+gltrace u
+gltrace_at u
+gltrace_corners u
+gltrace_draws u
+gltrace_frames u
+gltrace_function u
+gltrace_lit u
+gltrace_look u
+gltrace_place u
+gltrace_shaders u
+gltrace_uniforms u
+glwait u
+glyes u
+gpu k
+gpu_cached k
+gpu_exact k
+gpu_keep k
+gpu_log k
+hakios_kver k
+haptic k
+haptic_effect k
+hv_wdt_pet k
+loader_return_after kl
+machine_name k
+membench k
+mic k
+mic_adc k
+mic_input k
+mic_main k
+mic_secs k
+mic_tap k
+mic_test k
+modem k
+modem_again k
+modem_apn k
+modem_buffer k
+modem_data_nobind k
+modem_data_off k
+modem_data_wait k
+modem_dpm_off k
+modem_ipa k
+modem_ipa_bus_off k
+modem_ipa_data_off k
+modem_ipa_data_trace k
+modem_ipa_fw k
+modem_ipa_fw_at k
+modem_ipa_gsi_enable k
+modem_ipa_item k
+modem_ipa_no_probe k
+modem_ipa_quiet k
+modem_ipa_raw k
+modem_ipa_routes k
+modem_ipa_skip_uc k
+modem_ipa_smmu_off k
+modem_keep k
+modem_listen k
+modem_nas_wait k
+modem_new k
+modem_no_ipa_qmi k
+modem_no_nav k
+modem_no_tftp k
+modem_online k
+modem_pause k
+modem_return k
+modem_rmtfs_delay k
+modem_rmtfs_rw_fake k
+modem_rmtfs_rw_off k
+modem_share_off k
+modem_share_test k
+modem_sim_probe_off k
+modem_sim_switch_off k
+modem_step k
+modem_wait k
+modem_wda_off k
+net_names k
+net_trace k
+privs k
+rd kl
+rec_mb k
+rec_ring k
+rec_secs k
+rec_sound k
+rec_sound_fed k
+rec_sound_mic k
+rec_start k
+rec_step k
+regtrace k
+return_cpu k
+return_panic k
+root_apfs u
+sb_delay u
+serial l
+small_cores k
+small_cores_after k
+soc_cmd_db k
+soc_gsi_base k
+soc_imem k
+soc_ipa_base k
+soc_ipa_fw k
+soc_ipa_stream k
+soc_ipa_stream_uc k
+soc_mpss_mem k
+soc_pas_ipa k
+soc_pas_mpss k
+soc_smem k
+sound k
+sound_below k
+sound_gain k
+sound_guard_as k
+sound_pause k
+sound_secs k
+speaker_probe k
+surf_clear k
+surftrace k
+surftrace_of k
+switcher_wallpaper u
+syssleep k
+systrace k
+systrace_name k
+torch kl
+torch_max_s k
+torch_secs k
+touch_flip k
+touch_lat ku
+touch_poll_us k
+touch_rate k
+touch_spi_hz k
+touchscreen k
+ufs l
+ufs_bench k
+ufs_check k
+ufs_native kl
+ufs_native_bench k
+ufs_native_buffer k
+ufs_native_check k
+ufs_native_hang k
+ufs_native_leave k
+ufs_native_slots k
+ufs_native_spin k
+ufs_probe l
+ufs_shared_pa k
+ufs_write kl
+ustacks k
+ustacks_at k
+ustacks_count k
+ustacks_ms k
+ustacks_threads k
+ustacks_tname k
+var_save_ms k
+var_store u
+vblur u
+virtio_blk k
+virtio_input k
+virtio_net k
+virtio_sound k
+wifi k
+wifi_again k
+wifi_ask k
+wifi_ba k
+wifi_cal k
+wifi_dirty k
+wifi_file k
+wifi_fine k
+wifi_hold k
+wifi_irq k
+wifi_join k
+wifi_keep k
+wifi_listen k
+wifi_loud k
+wifi_lx k
+wifi_lx_step k
+wifi_mac k
+wifi_mission k
+wifi_new k
+wifi_pause k
+wifi_quiet k
+wifi_radio_read k
+wifi_ready k
+wifi_return k
+wifi_scan k
+wifi_smmu k
+wifi_station k
+wifi_step k
+wifi_wait k
+wifi_watch k
+wifi_wide k
+xpcproxy_idversion k
diff --git a/docs/boot-args.md b/docs/boot-args.md
new file mode 100644
index 0000000..3c01b11
--- /dev/null
+++ b/docs/boot-args.md
@@ -0,0 +1,388 @@
+# Boot-arguments
+
+Made by `tools/boot-args.py --markdown`; CI fails if it is out of date with the source (`tools/boot-args.py --check`).
+
+Every argument that the kernel, the loader or user space of this port reads, and which file reads it. **304 arguments**: 255 read by the kernel, 14 by the loader, 44 by user space (one is read in more than one place).
+
+This is a catalogue of what exists and who reads it, not a manual. What an argument means is in the head of the file that reads it. The stable switches have a symbol in the configuration (`tools/hakios-config.py help SYMBOL`, `docs/configs.md`); the rest are the knobs of bring-up (a driver's steps, pauses, traces, test modes) and can change with the driver. Any of them can be given in a configuration with `CONFIG_BOOTARGS="name=value ..."`, which checks that each name is in this list.
+
+Layers: **K** the kernel, **L** the loader, **U** user space (through `sysctl kern.bootargs`).
+
+## GPU and display (67)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `adreno` | K | `hakios.adreno.c` | | |
+| `adreno_blind` | K | `hakios.adreno.c` | | |
+| `adreno_dirty` | K | `hakios.adreno.c` | | |
+| `adreno_fine` | K | `hakios.adreno.c` | | |
+| `adreno_keep` | K | `hakios.adreno.c` | | |
+| `adreno_only` | K | `hakios.adreno.c` | | |
+| `adreno_pause` | K | `hakios.adreno.c` | | |
+| `adreno_return` | K | `hakios.adreno.c` | | |
+| `adreno_skip` | K | `hakios.adreno.c` | | |
+| `adreno_speed` | K | `hakios.adreno.c` | | |
+| `adreno_stream1` | K | `hakios.adreno.c` | | |
+| `adreno_watch` | K | `hakios.adreno.c` | | |
+| `display_probe` | K | `hakios.adreno.c` | | |
+| `fb_beat` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `fb_diff` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `fb_filter` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `fb_hz` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `fb_queue` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `fb_threads` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `fbheight` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `fbscale` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `fbtrace` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `fbwidth` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `glblit` | U | `eagl.c` | | |
+| `glcensus` | U | `eagl.c` | | |
+| `glcopy` | U | `eagl.c` | | |
+| `glenv` | U | `eagl.c` | | |
+| `glfetch` | U | `eagl.c` | | |
+| `glframes` | U | `eagl.c` | | |
+| `glgroup` | U | `eagl.c` | | |
+| `glnumbers` | U | `eagl.c` | | |
+| `glplain` | U | `eagl.c` | | |
+| `glprecision` | U | `eagl.c` | | |
+| `glshaders` | U | `eagl.c` | | |
+| `glshow` | U | `eagl.c` | | |
+| `glshow_part` | U | `eagl.c` | | |
+| `glshow_zoom` | U | `eagl.c` | | |
+| `glskip` | U | `eagl.c` | | |
+| `glslow` | U | `eagl.c` | | |
+| `glsync` | U | `eagl.c` | | |
+| `gltrace` | U | `eagl.c` | | |
+| `gltrace_at` | U | `eagl.c` | | |
+| `gltrace_corners` | U | `eagl.c` | | |
+| `gltrace_draws` | U | `eagl.c` | | |
+| `gltrace_frames` | U | `eagl.c` | | |
+| `gltrace_function` | U | `eagl.c` | | |
+| `gltrace_lit` | U | `eagl.c` | | |
+| `gltrace_look` | U | `eagl.c` | | |
+| `gltrace_place` | U | `eagl.c` | | |
+| `gltrace_shaders` | U | `eagl.c` | | |
+| `gltrace_uniforms` | U | `eagl.c` | | |
+| `glwait` | U | `eagl.c` | | |
+| `gpu` | K | `hakios.adreno.c` | `CONFIG_GPU` | |
+| `gpu_cached` | K | `hakios.gpu.cpp` | | |
+| `gpu_exact` | K | `hakios.adreno.c` | | |
+| `gpu_keep` | K | `hakios.gpu.cpp` | | |
+| `gpu_log` | K | `hakios.adreno.c` | | |
+| `rec_mb` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `rec_ring` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `rec_secs` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `rec_start` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `rec_step` | K | `MiniIOMobileFramebuffer.cpp` | | |
+| `surf_clear` | K | `MiniIOSurface.cpp` | | |
+| `surftrace` | K | `MiniIOSurface.cpp` | | |
+| `surftrace_of` | K | `MiniIOSurface.cpp` | | |
+| `touch_lat` | KU | `MiniIOMobileFramebuffer.cpp`, `eagl.c`, `hakios.goodix.c`, `hakios.gpu.cpp`, `hakios.input.c`, `inject.c`, `inject_sb.c` | | |
+| `vblur` | U | `eagl.c` | | |
+
+## Security stand-ins (1)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `privs` | K | `kern_minimac.c` | | |
+
+## Wi-Fi (31)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `wifi` | K | `hakios.wifi.c` | `CONFIG_WIFI` | |
+| `wifi_again` | K | `hakios.wifi.c` | | |
+| `wifi_ask` | K | `hakios.wifi.c` | | |
+| `wifi_ba` | K | `lx_80211.c` | | implied by wifi=1 |
+| `wifi_cal` | K | `hakios.wlfw.c` | | |
+| `wifi_dirty` | K | `hakios.wifi.c` | | |
+| `wifi_file` | K | `hakios.wifi.c` | | |
+| `wifi_fine` | K | `hakios.wifi.c` | | |
+| `wifi_hold` | K | `lx_bus.c` | | |
+| `wifi_irq` | K | `lx_bus.c` | | implied by wifi=1 |
+| `wifi_join` | K | `lx_bus.c` | | |
+| `wifi_keep` | K | `hakios.wifi.c` | | implied by wifi=1 |
+| `wifi_listen` | K | `hakios.wifi.c` | | |
+| `wifi_loud` | K | `hakios.wifi.c` | | |
+| `wifi_lx` | K | `hakios.wifi.c`, `lx_bus.c` | | implied by wifi=1 (as 2) |
+| `wifi_lx_step` | K | `lx_base.c` | | |
+| `wifi_mac` | K | `hakios.wifi.c` | | |
+| `wifi_mission` | K | `hakios.wlfw.c` | | |
+| `wifi_new` | K | `hakios.wifi.c` | | |
+| `wifi_pause` | K | `hakios.wifi.c` | | |
+| `wifi_quiet` | K | `lx_bus.c` | | |
+| `wifi_radio_read` | K | `hakios.wifi.c` | | |
+| `wifi_ready` | K | `hakios.wlfw.c` | | |
+| `wifi_return` | K | `hakios.wifi.c` | | |
+| `wifi_scan` | K | `lx_bus.c` | | |
+| `wifi_smmu` | K | `hakios.wifi.c` | | implied by wifi=1 (as 2) |
+| `wifi_station` | K | `lx_bus.c` | | implied by wifi=1 |
+| `wifi_step` | K | `hakios.wifi.c` | | |
+| `wifi_wait` | K | `hakios.wifi.c` | | |
+| `wifi_watch` | K | `hakios.wifi.c` | | |
+| `wifi_wide` | K | `lx_80211.c` | | implied by wifi=1 |
+
+## Cellular (53)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `modem` | K | `hakios.mpss.c` | `CONFIG_MODEM` | |
+| `modem_again` | K | `hakios.mpss.c` | `CONFIG_MODEM_AGAIN` | |
+| `modem_apn` | K | `hakios.mpss.c` | | |
+| `modem_buffer` | K | `hakios.mpss.c` | `CONFIG_MODEM_BUFFER` | |
+| `modem_data_nobind` | K | `hakios.mpss.c` | | |
+| `modem_data_off` | K | `hakios.mpss.c` | | |
+| `modem_data_wait` | K | `hakios.mpss.c` | | |
+| `modem_dpm_off` | K | `hakios.mpss.c` | | |
+| `modem_ipa` | K | `hakios.mpss.c` | | |
+| `modem_ipa_bus_off` | K | `hakios.mpss.c` | | |
+| `modem_ipa_data_off` | K | `hakios.ipa.c` | | |
+| `modem_ipa_data_trace` | K | `hakios.cell.c`, `hakios.ipa.c` | | |
+| `modem_ipa_fw` | K | `hakios.mpss.c` | | |
+| `modem_ipa_fw_at` | K | `hakios.mpss.c` | | |
+| `modem_ipa_gsi_enable` | K | `hakios.mpss.c` | | |
+| `modem_ipa_item` | K | `hakios.mpss.c` | | |
+| `modem_ipa_no_probe` | K | `hakios.mpss.c` | | |
+| `modem_ipa_quiet` | K | `hakios.mpss.c` | | |
+| `modem_ipa_raw` | K | `hakios.mpss.c` | | |
+| `modem_ipa_routes` | K | `hakios.mpss.c` | | |
+| `modem_ipa_skip_uc` | K | `hakios.mpss.c` | | |
+| `modem_ipa_smmu_off` | K | `hakios.mpss.c` | | |
+| `modem_keep` | K | `hakios.mpss.c` | | |
+| `modem_listen` | K | `hakios.mpss.c` | | |
+| `modem_nas_wait` | K | `hakios.mpss.c` | | |
+| `modem_new` | K | `hakios.mpss.c` | | |
+| `modem_no_ipa_qmi` | K | `hakios.mpss.c` | | |
+| `modem_no_nav` | K | `hakios.mpss.c` | | |
+| `modem_no_tftp` | K | `hakios.mpss.c` | | |
+| `modem_online` | K | `hakios.mpss.c` | | |
+| `modem_pause` | K | `hakios.mpss.c` | | |
+| `modem_return` | K | `hakios.mpss.c` | | |
+| `modem_rmtfs_delay` | K | `hakios.mpss.c` | | |
+| `modem_rmtfs_rw_fake` | K | `hakios.mpss.c` | | |
+| `modem_rmtfs_rw_off` | K | `hakios.mpss.c` | | |
+| `modem_share_off` | K | `hakios.mpss.c` | | |
+| `modem_share_test` | K | `hakios.mpss.c` | | |
+| `modem_sim_probe_off` | K | `hakios.mpss.c` | | |
+| `modem_sim_switch_off` | K | `hakios.mpss.c` | | |
+| `modem_step` | K | `hakios.mpss.c` | | |
+| `modem_wait` | K | `hakios.mpss.c` | | |
+| `modem_wda_off` | K | `hakios.mpss.c` | | |
+| `soc_cmd_db` | K | `hakios.mpss.c` | | |
+| `soc_gsi_base` | K | `hakios.ipa.c` | | |
+| `soc_imem` | K | `hakios.mpss.c` | | |
+| `soc_ipa_base` | K | `hakios.ipa.c` | | |
+| `soc_ipa_fw` | K | `hakios.mpss.c` | | |
+| `soc_ipa_stream` | K | `hakios.mpss.c` | | |
+| `soc_ipa_stream_uc` | K | `hakios.mpss.c` | | |
+| `soc_mpss_mem` | K | `hakios.mpss.c` | | |
+| `soc_pas_ipa` | K | `hakios.mpss.c` | | |
+| `soc_pas_mpss` | K | `hakios.mpss.c` | | |
+| `soc_smem` | K | `hakios.mpss.c` | | |
+
+## Audio and battery (31)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `adsp` | K | `hakios.adsp.c` | `CONFIG_ADSP` | |
+| `adsp_again` | K | `hakios.adsp.c` | | |
+| `adsp_apr_wait` | K | `hakios.adsp.c` | | |
+| `adsp_keep` | K | `hakios.adsp.c` | | |
+| `adsp_listen` | K | `hakios.adsp.c` | | |
+| `adsp_new` | K | `hakios.adsp.c` | | |
+| `adsp_pause` | K | `hakios.adsp.c` | | |
+| `adsp_return` | K | `hakios.adsp.c` | | |
+| `adsp_step` | K | `hakios.adsp.c` | | |
+| `adsp_wait` | K | `hakios.adsp.c` | | |
+| `battery` | KL | `hakios.adsp.c`, `hakios.battery.c`, `loader.c` | | |
+| `battery_shared_pa` | K | `hakios.battery.c` | | the loader (the address of its charger page) |
+| `battmgr` | K | `hakios.adsp.c` | | |
+| `mic` | K | `hakios.mic.c` | `CONFIG_MIC` | |
+| `mic_adc` | K | `hakios.mic.c` | | |
+| `mic_input` | K | `hakios.mic.c` | | |
+| `mic_main` | K | `hakios.mic.c` | | |
+| `mic_secs` | K | `hakios.mic.c` | | |
+| `mic_tap` | K | `hakios.mic.c` | | |
+| `mic_test` | K | `hakios.mic.c` | | |
+| `rec_sound` | K | `hakios.audio.c` | | |
+| `rec_sound_fed` | K | `hakios.audio.c` | | |
+| `rec_sound_mic` | K | `hakios.audio.c` | | |
+| `sound` | K | `hakios.sound.c` | `CONFIG_SOUND` | |
+| `sound_below` | K | `hakios.sound.c` | | |
+| `sound_gain` | K | `hakios.sound.c` | | |
+| `sound_guard_as` | K | `hakios.sound.c` | | |
+| `sound_pause` | K | `hakios.sound.c` | | |
+| `sound_secs` | K | `hakios.sound.c` | | |
+| `speaker_probe` | K | `hakios.speaker.c` | | |
+| `virtio_sound` | K | `hakios.virtio_sound.c` | | |
+
+## Cameras (13)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `cam` | KL | `hakios.camera.c`, `loader.c` | `CONFIG_CAM` | |
+| `cam_after` | K | `hakios.camera.c` | | |
+| `cam_fake` | K | `hakios.camera.c` | | |
+| `cam_fake_fps` | K | `hakios.camera.c` | | |
+| `cam_frames` | K | `hakios.camera.c` | | |
+| `cam_gain` | K | `hakios.camera.c` | | |
+| `cam_keep_mb` | K | `hakios.camera.c` | | |
+| `cam_mode` | K | `hakios.camera.c` | | |
+| `cam_pattern` | K | `hakios.camera.c` | | |
+| `cam_sensor` | K | `hakios.camera.c` | | |
+| `cam_settle` | K | `hakios.camera.c` | | |
+| `cam_shutter` | K | `hakios.camera.c` | | |
+| `cam_vblank` | K | `hakios.camera.c` | | |
+
+## Touch and buttons (8)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `buttons` | K | `hakios.buttons.c` | | |
+| `buttons_steps` | K | `hakios.buttons.c` | | |
+| `touch_flip` | K | `hakios.goodix.c` | | |
+| `touch_poll_us` | K | `hakios.goodix.c` | | |
+| `touch_rate` | K | `hakios.goodix.c` | | |
+| `touch_spi_hz` | K | `hakios.goodix.c` | | |
+| `touchscreen` | K | `hakios.buttons.c`, `hakios.goodix.c` | `CONFIG_TOUCHSCREEN` | |
+| `virtio_input` | K | `hakios.virtio_input.c` | | |
+
+## Storage and APFS (43)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `apfs_cheap` | K | `apfs_vfsops.c` | | |
+| `apfs_check` | K | `hakios.apfs_check.c` | | |
+| `apfs_chunk` | K | `hakios.apfs_check.c` | | |
+| `apfs_contents` | K | `hakios.apfs_check.c` | | |
+| `apfs_depth` | K | `hakios.apfs_check.c` | | |
+| `apfs_dev` | K | `hakios.apfs_check.c` | | |
+| `apfs_hash` | K | `hakios.apfs_check.c` | | |
+| `apfs_max` | K | `hakios.apfs_check.c` | | |
+| `apfs_meta_cluster` | K | `apfs_vfsops.c` | | |
+| `apfs_mnt` | K | `hakios.apfs_check.c` | | |
+| `apfs_par` | K | `apfs_vfsops.c` | | |
+| `apfs_root_c` | K | `apfs_vfsops.c` | | |
+| `apfs_root_v` | K | `apfs_vfsops.c` | | |
+| `apfs_round` | K | `apfs_vfsops.c` | | |
+| `apfs_skip` | K | `hakios.apfs_check.c` | | |
+| `apfs_sparse` | K | `hakios.sparse.c` | | |
+| `apfs_store_len` | K | `hakios.apfs_check.c` | | |
+| `apfs_store_note` | K | `hakios.apfs_check.c` | | |
+| `apfs_store_seed` | K | `hakios.apfs_check.c` | | |
+| `apfs_subtree` | K | `hakios.apfs_check.c` | | |
+| `apfs_threads` | K | `hakios.apfs_check.c` | | |
+| `apfs_ubc_read` | K | `apfs_vfsops.c` | | |
+| `apfs_volume` | K | `hakios.apfs_check.c` | | |
+| `apfs_volume_at` | K | `hakios.apfs_check.c` | | |
+| `apfs_walkers` | K | `hakios.apfs_check.c` | | |
+| `apfs_write_at` | K | `hakios.apfs_check.c` | | |
+| `apfs_write_byte` | K | `hakios.apfs_check.c` | | |
+| `apfs_write_len` | K | `hakios.apfs_check.c` | | |
+| `apfs_write_path` | K | `hakios.apfs_check.c` | | |
+| `ufs_bench` | K | `hakios.ufs.c` | | |
+| `ufs_check` | K | `hakios.ufs.c` | | |
+| `ufs_native` | KL | `hakios.ufs.c`, `loader.c` | | |
+| `ufs_native_bench` | K | `hakios.ufs.c` | | |
+| `ufs_native_buffer` | K | `hakios.ufshc.c` | | |
+| `ufs_native_check` | K | `hakios.ufs.c` | | |
+| `ufs_native_hang` | K | `hakios.ufshc.c` | | |
+| `ufs_native_leave` | K | `hakios.ufshc.c` | | |
+| `ufs_native_slots` | K | `hakios.ufshc.c` | | |
+| `ufs_native_spin` | K | `hakios.ufshc.c` | | |
+| `ufs_shared_pa` | K | `hakios.ufs.c` | | the loader (the address of its block-service page) |
+| `ufs_write` | KL | `hakios.ufs.c`, `loader.c` | `CONFIG_UFS_WRITE` | |
+| `var_save_ms` | K | `hakios.ufs.c` | | |
+| `virtio_blk` | K | `hakios.virtio_blk.c` | | |
+
+## Network (3)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `net_names` | K | `hakios.net.c` | `CONFIG_NET_NAMES` | |
+| `net_trace` | K | `hakios.net.c` | `CONFIG_NET_TRACE` | |
+| `virtio_net` | K | `hakios.virtio_net.c` | `CONFIG_VIRTIO_NET` | |
+
+## Haptics and torch (5)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `haptic` | K | `hakios.haptic.c` | `CONFIG_HAPTIC` | |
+| `haptic_effect` | K | `hakios.haptic.c` | | |
+| `torch` | KL | `hakios.torch.c`, `loader.c` | | |
+| `torch_max_s` | K | `hakios.torch.c` | | |
+| `torch_secs` | K | `hakios.torch.c` | | |
+
+## Version (1)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `hakios_kver` | K | `hakios.version.c` | | the loader (from the payload's kernel.ver) |
+
+## CPU, memory and boot (23)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `applog` | K | `(patch)` | | |
+| `applog_name` | K | `(patch)` | | |
+| `bootcpu` | KL | `loader.c`, `loader_return.c` | `CONFIG_BOOTCPU` | |
+| `cpufreq` | K | `hakios.cpufreq.c` | `CONFIG_CPUFREQ` | |
+| `cpuload` | K | `hakios.cpufreq.c` | | |
+| `ddr` | K | `hakios.cpufreq.c` | | |
+| `ddr_rest` | K | `hakios.cpufreq.c` | | |
+| `ddr_vote` | K | `hakios.cpufreq.c` | | |
+| `epoch` | K | `GenericARMPE.cpp` | | xl (the host's clock) |
+| `hv_wdt_pet` | K | `loader_return.c` | | the loader, when it has armed the watchdog (the runner also passes it) |
+| `loader_return_after` | KL | `loader.c`, `loader_return.c` | | xl (XL_SECS) |
+| `machine_name` | K | `GenericARMPE.cpp` | | |
+| `membench` | K | `hakios.cpufreq.c` | | |
+| `rd` | KL | `(patch)`, `loader.c` | | |
+| `regtrace` | K | `(patch)` | | |
+| `return_cpu` | K | `loader_return.c` | | |
+| `return_panic` | K | `loader_return.c` | | |
+| `small_cores` | K | `(patch)` | | |
+| `small_cores_after` | K | `GenericARMPE.cpp` | | |
+| `syssleep` | K | `(patch)` | | |
+| `systrace` | K | `(patch)`, `user_exception_trace.c` | | |
+| `systrace_name` | K | `(patch)` | | |
+| `xpcproxy_idversion` | K | `(patch)` | | |
+
+## Debugging (6)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `ustacks` | K | `user_exception_trace.c` | | |
+| `ustacks_at` | K | `user_exception_trace.c` | | |
+| `ustacks_count` | K | `user_exception_trace.c` | | |
+| `ustacks_ms` | K | `user_exception_trace.c` | | |
+| `ustacks_threads` | K | `user_exception_trace.c` | | |
+| `ustacks_tname` | K | `user_exception_trace.c` | | |
+
+## Loader (6)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `cpumask` | L | `loader.c` | | |
+| `cpus` | L | `loader.c` | `CONFIG_CPUS` | |
+| `gamut` | L | `loader.c` | | |
+| `serial` | L | `loader.c` | | |
+| `ufs` | L | `loader.c` | `CONFIG_UFS` | |
+| `ufs_probe` | L | `loader.c` | | |
+
+## User space (13)
+
+| Argument | Layer | Read by | Configuration | Set by |
+|---|---|---|---|---|
+| `autounlock` | U | `inject_sb.c` | | |
+| `ca_vbl` | U | `inject.c` | | |
+| `caenv` | U | `inject.c` | | |
+| `cc_fade` | U | `inject_sb.c` | | |
+| `gl` | U | `inject.c`, `inject_sb.c` | | |
+| `glcompile` | U | `inject.c` | | |
+| `glno` | U | `inject.c` | | |
+| `glsb3` | U | `inject.c` | | |
+| `glyes` | U | `inject.c` | | |
+| `root_apfs` | U | `init.c` | | |
+| `sb_delay` | U | `inject_sb.c` | | xl (XL_SB_DELAY) |
+| `switcher_wallpaper` | U | `inject_sb.c` | | |
+| `var_store` | U | `init.c` | `CONFIG_VAR_STORE` | |
diff --git a/tools/boot-args-test.py b/tools/boot-args-test.py
new file mode 100644
index 0000000..c4aab7b
--- /dev/null
+++ b/tools/boot-args-test.py
@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""tools/boot-args.py: every form in which a boot-argument is read is found, and what only looks like one is not.
+
+Each form has a case that must be found, and the ways a scan can be wrong have cases that must NOT be found. The
+scanner missed whole families while it was written, each time a form it did not know: the wrappers that take the name as
+a string (option("modem_again"), lx_os_option("wifi_irq")), XNU's TUNABLE(type, var, "fb_beat", 1), user space's own
+helper boot_arg("var_store"). The check at the end is the guard: a driver that adds an argument makes CI say the
+catalogue is out of date.
+"""
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+TOOL = os.path.join(HERE, "boot-args.py")
+failures = []
+
+
+def check(label, ok, detail=""):
+ print("%s %s" % ("ok " if ok else "FAIL", label))
+ if not ok:
+ failures.append(label)
+ if detail:
+ print(" " + str(detail).strip().replace("\n", "\n ")[:500])
+
+
+def repo(files):
+ d = tempfile.mkdtemp(prefix="boot-args-test-")
+ subprocess.run(["git", "init", "-q", d], check=True)
+ for name, text in files.items():
+ path = os.path.join(d, name)
+ os.makedirs(os.path.dirname(path), exist_ok=True)
+ open(path, "w", encoding="utf-8", newline="\n").write(text)
+ subprocess.run(["git", "-C", d, "add", "-A"], check=True, capture_output=True)
+ return d
+
+
+def run(d, *args):
+ return subprocess.run([sys.executable, TOOL, "--root", d, *args], capture_output=True, text=True)
+
+
+def found(d):
+ """{name: layers} from --lst."""
+ out = {}
+ for line in run(d, "--lst").stdout.splitlines():
+ name, _, layers = line.partition("\t")
+ out[name] = layers
+ return out
+
+
+FILES = {
+ # kernel: the direct forms, in the old place (xnu/files) and the new one (drivers/)
+ "xnu/files/bsd/dev/hakios.adreno.c": 'void f(void) { PE_parse_boot_argn("k_direct", &v, sizeof(v)); PE_parse_boot_arg_str("k_string", b, 8); }\n',
+ "drivers/gpu/hakios.gpu.cpp": 'static TUNABLE(uint32_t, gOnTheBeat, "k_tunable", 1);\nstatic TUNABLE_WRITEABLE(uint32_t, gW, "k_writeable", 0);\n',
+ # kernel: a file with its own option(name) that calls PE_parse_boot_argn(name)
+ "xnu/files/bsd/dev/hakios.mpss.c": 'static bool\noption(const char *name)\n{\n\treturn PE_parse_boot_argn(name, &v, 4);\n}\nvoid g(void) { if (option("k_wrapped")) {} }\n',
+ # kernel: Wi-Fi, through the helper and through the Linux layer
+ "xnu/files/bsd/dev/hakios.wifi.c": 'void h(void) { hakios_wifi_option("k_wifi_helper"); }\n',
+ "wifi/lx/src/lx_bus.c": 'void i(void) { if (lx_os_option("k_wifi_lx")) {} }\n',
+ # the loader
+ "xnuloader/loader.c": 'static void j(const char *c) { if (starts_with(c, "l_arg=") || starts_with(c, "ku_both=")) {} }\n',
+ # user space: strstr on the kern.bootargs buffer, and its own boot_arg() helper
+ "userland/src/eagl.c": 'void k(char *arguments) { strstr(arguments, "u_strstr=1"); strstr(arguments, "ku_both="); }\n',
+ "userland/src/init.c": 'static const char *\nboot_arg(const char *name)\n{ return 0; }\nvoid m(void) { boot_arg("u_helper"); }\n',
+ # the kernel also reads ku_both
+ "xnu/files/bsd/dev/hakios.net.c": 'void n(void) { PE_parse_boot_argn("ku_both", &v, 4); }\n',
+ # NOT arguments: must not be found
+ "xnu/files/bsd/dev/hakios.other.c": 'static bool option(int x);\nvoid p(void) { option("not_k_no_definition"); }\n', # option() here is no wrapper: no definition of option(const char *name)
+ "xnu/files/bsd/dev/hakios.comment.c": '/* boot-arg adreno_zap=0 for the second run; nothing reads it now */\nvoid q(void) {}\n',
+ "userland/src/apfs_mmap_test.c": 'void r(char *line) { strstr(line, "metadata"); strstr(line, "not_u_other=1"); }\n', # strstr on another buffer
+ "xnu/files/bsd/dev/hakios.dt.c": 'static TUNABLE_DT(uint32_t, gD, "/chosen", "name", "not_k_dt", 0, 0);\n', # a device-tree tunable: not a plain boot-arg
+}
+
+d = repo(FILES)
+try:
+ got = found(d)
+ for name, layers in (("k_direct", "k"), ("k_string", "k"), ("k_tunable", "k"), ("k_writeable", "k"), ("k_wrapped", "k"),
+ ("k_wifi_helper", "k"), ("k_wifi_lx", "k"), ("l_arg", "l"), ("u_strstr", "u"), ("u_helper", "u"),
+ ("ku_both", "klu")):
+ check("found: %-14s layers %s" % (name, layers), got.get(name) == layers, "got %r" % got.get(name))
+ for name in ("not_k_no_definition", "adreno_zap", "metadata", "not_u_other", "not_k_dt", "name", "arguments"):
+ check("NOT found: %s" % name, name not in got, "it is in the catalogue as %r" % got.get(name))
+ check("drivers/ is scanned as well as xnu/files/", "k_tunable" in got)
+ check("the groups: the GPU file's argument is under GPU and display", "## GPU and display" in run(d, "--markdown").stdout)
+ check("the page says which layers read ku_both", "| `ku_both` | KLU |" in run(d, "--markdown").stdout, run(d, "--markdown").stdout[-400:])
+
+ # the check: missing files; current files; a driver that adds an argument; a table symbol nobody reads
+ r = run(d, "--check")
+ check("--check: files missing -> fails and says what to run", r.returncode != 0 and "boot-args.py --markdown" in r.stdout, r.stdout)
+ os.makedirs(os.path.join(d, "docs"), exist_ok=True)
+ os.makedirs(os.path.join(d, "configs"), exist_ok=True)
+ open(os.path.join(d, "docs", "boot-args.md"), "w", newline="\n").write(run(d, "--markdown").stdout)
+ open(os.path.join(d, "configs", "boot-args.lst"), "w", newline="\n").write(run(d, "--lst").stdout)
+ check("--check: current files -> passes", run(d, "--check").returncode == 0, run(d, "--check").stdout)
+ open(os.path.join(d, "xnu", "files", "bsd", "dev", "hakios.adreno.c"), "a").write('void more(void) { PE_parse_boot_argn("a_new_one", &v, 4); }\n')
+ subprocess.run(["git", "-C", d, "add", "-A"], check=True, capture_output=True)
+ r = run(d, "--check")
+ check("--check: a driver adds an argument -> the catalogue is out of date, fails", r.returncode != 0 and "out of date" in r.stdout, r.stdout)
+ os.makedirs(os.path.join(d, "tools"), exist_ok=True)
+ open(os.path.join(d, "tools", "hakios-config.py"), "w").write('SYMBOLS = [\n ("GHOST", "bool", "nobody_reads_this", "x", None, None),\n]\n')
+ subprocess.run(["git", "-C", d, "add", "-A"], check=True, capture_output=True)
+ open(os.path.join(d, "docs", "boot-args.md"), "w", newline="\n").write(run(d, "--markdown").stdout)
+ open(os.path.join(d, "configs", "boot-args.lst"), "w", newline="\n").write(run(d, "--lst").stdout)
+ r = run(d, "--check")
+ check("--check: a configuration symbol whose argument nobody reads -> fails", r.returncode != 0 and "nobody_reads_this" in r.stdout, r.stdout)
+finally:
+ shutil.rmtree(d, ignore_errors=True)
+
+# the real tree: the committed catalogue is current, and the table's symbols are all read somewhere
+ROOT = os.path.dirname(HERE)
+r = subprocess.run([sys.executable, TOOL, "--check"], capture_output=True, text=True, cwd=ROOT)
+check("the real tree: docs/boot-args.md and configs/boot-args.lst are current", r.returncode == 0, r.stdout)
+
+if failures:
+ sys.exit("boot-args-test: %d FAILED" % len(failures))
+print("boot-args-test: all passed")
diff --git a/tools/boot-args.py b/tools/boot-args.py
new file mode 100644
index 0000000..7382e3f
--- /dev/null
+++ b/tools/boot-args.py
@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""The catalogue of every boot-argument that the kernel, the loader and user space read.
+
+usage: tools/boot-args.py [--markdown | --lst | --check] [--root DIR]
+
+ (none) the catalogue, as text, grouped by driver
+ --markdown the catalogue as docs/boot-args.md has it
+ --lst the names, as configs/boot-args.lst has them (what tools/hakios-config.py checks CONFIG_BOOTARGS against)
+ --check exit 1 if docs/boot-args.md or configs/boot-args.lst is out of date with the source (CI runs this)
+
+Why it exists. The kernel of this port is configured on its command line, and every driver reads its own
+arguments: 194 in the kernel's files, 14 in the loader, 26 in user space. A handful of them are stable switches
+that tools/hakios-config.py describes (CONFIG_GPU, CONFIG_WIFI ...). The rest are the knobs of bring-up: a driver's
+steps, pauses, traces, test modes. Nobody can keep a hand-written list of two hundred of them true, so this finds
+them in the source: a name that a driver reads is in the catalogue, one that nobody reads is not, and the check
+fails the build when the two files disagree with the code. It says WHICH driver reads an argument and WHERE; what
+an argument means is in the head of that file, and for the stable ones in tools/hakios-config.py (`help SYMBOL`).
+
+What is looked for:
+ the kernel PE_parse_boot_argn("name" ...) and PE_parse_boot_arg_str("name" ...), in xnu/files/ and in the lines
+ xnu/hakios.patch adds to Apple's files
+ the loader starts_with(c, "name=...") on the payload's command line, in xnuloader/
+ user space a name given to strstr()/strncmp() on sysctl kern.bootargs, in userland/src/ (seen: sb_delay=, touch_lat=1,
+ ca_vbl=1 ...)
+"""
+import argparse
+import collections
+import os
+import re
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+
+KERNEL = re.compile(r'PE_parse_boot_arg(?:n|_str)?\(\s*"([A-Za-z0-9_.\-]+)"')
+# XNU's TUNABLE(type, variable, "boot-arg name", default) reads the argument at start-up, in the files of the display and GPU
+# drivers (C++) and in the sandbox stand-in: static TUNABLE(uint32_t, gOnTheBeat, "fb_beat", 1). Also TUNABLE_WRITEABLE and
+# TUNABLE_STR. (TUNABLE_DT, whose third argument is a device-tree path with slashes, does not match.)
+TUNABLE = re.compile(r'\bTUNABLE\w*\(\s*[^,()]+,\s*[^,()]+,\s*"([A-Za-z0-9_.\-]+)"')
+# Three drivers read their options through a small function that is given the name as a string, and the name is the
+# literal at the call: option("modem_again") in hakios.mpss.c and hakios.adsp.c (a static function in each), and for
+# Wi-Fi hakios_wifi_option("wifi_keep") with lx_os_option("wifi_irq") of the Linux layer in wifi/lx/src, which calls it.
+# A scan for PE_parse_boot_argn("...") alone misses all of them (about forty names), so these are scanned too.
+WRAPPED = re.compile(r'\b(?:hakios_wifi_option|lx_os_option)\(\s*"([a-z][a-z0-9_]*)"')
+OPTION_DEF = re.compile(r'^option\(const char \*name\)', re.M)
+OPTION_CALL = re.compile(r'\boption\(\s*"([a-z][a-z0-9_]*)"')
+# ... and user space has its own: boot_arg("var_store") in init.c (a static function that reads sysctl kern.bootargs)
+BOOT_ARG_DEF = re.compile(r'^boot_arg\(const char \*name\)', re.M)
+BOOT_ARG_CALL = re.compile(r'\bboot_arg\(\s*"([a-z][a-z0-9_]*)"')
+LOADER = re.compile(r'starts_with\((?:c|cmd|p|a|s), "([a-z][a-z0-9_.]*)=')
+# user space reads sysctl kern.bootargs into a buffer called arguments, args or argument, and looks in it with strstr:
+# strstr(arguments, "gltrace_at="), strstr(args, "touch_lat=1"): the name is what stands before the =
+USER = re.compile(r'strstr\(\s*(?:arguments|args|argument)\s*,\s*"([a-z][a-z0-9_]*)=')
+
+# the group an argument is listed under: by the file that reads it (the first match decides)
+GROUPS = [
+ ("GPU and display", r"hakios\.(adreno|gpu)\.|MiniIO(Surface|MobileFramebuffer)|gl_osmesa|eagl\.c"),
+ ("Security stand-ins", r"kern_minimac|miniamfi"),
+ ("Wi-Fi", r"hakios\.(wifi|wlfw|lx|sta|apple80211)\.|^lx_[a-z0-9]+\.c$"), # wifi/lx/src/lx_*.c: the Linux layer
+ ("Cellular", r"hakios\.(mpss|ipa|cell|nas|qmi)\."),
+ ("Audio and battery", r"hakios\.(adsp|audio|sound|speaker|mic|virtio_sound|battery)\."),
+ ("Cameras", r"hakios\.camera\."),
+ ("Touch and buttons", r"hakios\.(goodix|input|buttons|virtio_input)\."),
+ ("Storage and APFS", r"hakios\.(ufs|ufshc|virtio_blk|sparse|apfs_check)\.|apfs_vfsops\."),
+ ("Network", r"hakios\.(net|virtio_net)\."),
+ ("Haptics and torch", r"hakios\.(haptic|torch)\."),
+ ("Version", r"hakios\.version\."),
+ ("CPU, memory and boot", r"hakios\.cpufreq\.|GenericARMPE|loader_return|\(patch\)"),
+ ("Debugging", r"user_exception_trace"),
+ ("Loader", r"loader\.c"),
+ ("User space", r"."),
+]
+
+# who SETS an argument when it is not the person: verified in the loader's command-line assembly and in xl
+SET_BY = {
+ "ufs_shared_pa": "the loader (the address of its block-service page)",
+ "battery_shared_pa": "the loader (the address of its charger page)",
+ "hakios_kver": "the loader (from the payload's kernel.ver)",
+ "hv_wdt_pet": "the loader, when it has armed the watchdog (the runner also passes it)",
+ "epoch": "xl (the host's clock)",
+ "loader_return_after": "xl (XL_SECS)",
+ "sb_delay": "xl (XL_SB_DELAY)",
+ # wifi=1 is "all of it, by itself": hakios_wifi_option() answers these as if they were given (wifi_lx=2 wifi_smmu=2
+ # wifi_station=1 wifi_keep=1 wifi_irq=1 wifi_ba=1 wifi_wide=1) unless they are given otherwise
+ "wifi_lx": "implied by wifi=1 (as 2)",
+ "wifi_smmu": "implied by wifi=1 (as 2)",
+ "wifi_station": "implied by wifi=1",
+ "wifi_keep": "implied by wifi=1",
+ "wifi_irq": "implied by wifi=1",
+ "wifi_ba": "implied by wifi=1",
+ "wifi_wide": "implied by wifi=1",
+}
+
+
+def tracked(root):
+ out = subprocess.run(["git", "ls-files", "-z"], cwd=root, capture_output=True, check=True).stdout
+ return [p.decode() for p in out.split(b"\0") if p]
+
+
+def scan(root):
+ """{name: {"kernel": {files}, "loader": {files}, "user": {files}}} found in the tracked source."""
+ found = collections.defaultdict(lambda: {"kernel": set(), "loader": set(), "user": set()})
+ for f in tracked(root):
+ if not f.endswith((".c", ".cpp", ".m", ".h", ".patch")):
+ continue
+ try:
+ text = open(os.path.join(root, f), encoding="utf-8", errors="replace").read()
+ except OSError:
+ continue
+ base = os.path.basename(f)
+ if f == "xnu/hakios.patch":
+ text = "\n".join(l[1:] for l in text.splitlines() if l.startswith("+") and not l.startswith("+++"))
+ base = "(patch)"
+ # the kernel's side: where the drivers are kept (xnu/files/ until they moved to drivers/<subsystem>/) and the Linux layer
+ if f.startswith(("xnu/", "drivers/", "wifi/lx/src/")):
+ for m in KERNEL.finditer(text):
+ found[m.group(1)]["kernel"].add(base)
+ for m in WRAPPED.finditer(text):
+ found[m.group(1)]["kernel"].add(base)
+ for m in TUNABLE.finditer(text):
+ found[m.group(1)]["kernel"].add(base)
+ if OPTION_DEF.search(text): # a file that has its own option(name): its callers name arguments
+ for m in OPTION_CALL.finditer(text):
+ found[m.group(1)]["kernel"].add(base)
+ if f.startswith("xnuloader/") and f.endswith(".c"):
+ for m in LOADER.finditer(text):
+ found[m.group(1)]["loader"].add(base)
+ if f.startswith("userland/src/"):
+ for m in USER.finditer(text):
+ found[m.group(1)]["user"].add(base)
+ if BOOT_ARG_DEF.search(text):
+ for m in BOOT_ARG_CALL.finditer(text):
+ found[m.group(1)]["user"].add(base)
+ return found
+
+
+def group_of(files):
+ for group, pattern in GROUPS:
+ if any(re.search(pattern, f) for f in sorted(files)):
+ return group
+ return "User space"
+
+
+def symbols(root):
+ """{boot-arg: CONFIG_SYMBOL} of the table in tools/hakios-config.py."""
+ out = {}
+ path = os.path.join(root, "tools", "hakios-config.py")
+ if os.path.isfile(path):
+ for line in open(path, encoding="utf-8"):
+ m = re.match(r'\s+\("([A-Z0-9_]+)", "(?:bool|int|hex|str)", "([a-z0-9_]+)"', line)
+ if m:
+ out[m.group(2)] = "CONFIG_" + m.group(1)
+ return out
+
+
+def layers(d):
+ return "".join(letter for key, letter in (("kernel", "k"), ("loader", "l"), ("user", "u")) if d[key])
+
+
+def lst(found):
+ return "".join("%s\t%s\n" % (name, layers(d)) for name, d in sorted(found.items()))
+
+
+def markdown(found, config):
+ groups = collections.defaultdict(list)
+ for name, d in found.items():
+ groups[group_of(d["kernel"] | d["loader"] | d["user"])].append((name, d))
+ lines = [
+ "# Boot-arguments",
+ "",
+ "Made by `tools/boot-args.py --markdown`; CI fails if it is out of date with the source (`tools/boot-args.py --check`).",
+ "",
+ "Every argument that the kernel, the loader or user space of this port reads, and which file reads it. **%d arguments**: "
+ "%d read by the kernel, %d by the loader, %d by user space (one is read in more than one place)." % (
+ len(found), sum(1 for d in found.values() if d["kernel"]), sum(1 for d in found.values() if d["loader"]),
+ sum(1 for d in found.values() if d["user"])),
+ "",
+ "This is a catalogue of what exists and who reads it, not a manual. What an argument means is in the head of the file "
+ "that reads it. The stable switches have a symbol in the configuration (`tools/hakios-config.py help SYMBOL`, "
+ "`docs/configs.md`); the rest are the knobs of bring-up (a driver's steps, pauses, traces, test modes) and can change "
+ "with the driver. Any of them can be given in a configuration with `CONFIG_BOOTARGS=\"name=value ...\"`, which checks "
+ "that each name is in this list.",
+ "",
+ "Layers: **K** the kernel, **L** the loader, **U** user space (through `sysctl kern.bootargs`).",
+ "",
+ ]
+ for group in [g for g, _ in GROUPS if g in groups]:
+ rows = sorted(groups[group])
+ lines += ["## %s (%d)" % (group, len(rows)), "", "| Argument | Layer | Read by | Configuration | Set by |", "|---|---|---|---|---|"]
+ for name, d in rows:
+ files = sorted(d["kernel"] | d["loader"] | d["user"])
+ lines.append("| `%s` | %s | %s | %s | %s |" % (
+ name, "".join(x.upper() for x in layers(d)), ", ".join("`%s`" % f for f in files),
+ "`%s`" % config[name] if name in config else "", SET_BY.get(name, "")))
+ lines.append("")
+ return "\n".join(lines).rstrip() + "\n"
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ what = ap.add_mutually_exclusive_group()
+ what.add_argument("--markdown", action="store_true")
+ what.add_argument("--lst", action="store_true")
+ what.add_argument("--check", action="store_true")
+ ap.add_argument("--root", default=ROOT)
+ args = ap.parse_args()
+ root = os.path.abspath(args.root)
+ found = scan(root)
+ config = symbols(root)
+
+ if args.markdown:
+ sys.stdout.write(markdown(found, config))
+ elif args.lst:
+ sys.stdout.write(lst(found))
+ elif args.check:
+ bad = 0
+ for rel, want in (("docs/boot-args.md", markdown(found, config)), ("configs/boot-args.lst", lst(found))):
+ path = os.path.join(root, rel)
+ have = open(path, encoding="utf-8", newline="").read().replace("\r\n", "\n") if os.path.isfile(path) else None
+ if have != want:
+ bad += 1
+ print("boot-args: %s is %s: run tools/boot-args.py --%s > %s" % (
+ rel, "missing" if have is None else "out of date with the source", "markdown" if rel.endswith(".md") else "lst", rel))
+ unknown = sorted(a for a in config if a not in found)
+ for a in unknown:
+ bad += 1
+ print("boot-args: the configuration table names %s, which no driver reads" % a)
+ if not bad:
+ print("boot-args: %d arguments; docs/boot-args.md and configs/boot-args.lst are current; every configuration symbol "
+ "is an argument that is read" % len(found))
+ sys.exit(1 if bad else 0)
+ else:
+ by = collections.defaultdict(list)
+ for name, d in found.items():
+ by[group_of(d["kernel"] | d["loader"] | d["user"])].append((name, d))
+ for group in [g for g, _ in GROUPS if g in by]:
+ print("%s (%d)" % (group, len(by[group])))
+ for name, d in sorted(by[group]):
+ print(" %-26s %-3s %s" % (name, layers(d).upper(), ", ".join(sorted(d["kernel"] | d["loader"] | d["user"]))))
+
+
+if __name__ == "__main__":
+ main()