tree: c97b2c36c3f3e344ed64392f501ae91e0664eede [path history] [tgz]
  1. alias_workaround.cc
  2. alias_workaround.h
  3. alias_workaround_test.cc
  4. BUILD.gn
  5. c_ulib_header_output.cc
  6. c_ulib_header_output_test.cc
  7. category_output.cc
  8. category_output_test.cc
  9. cdecl_output.cc
  10. cdecl_output_test.cc
  11. fidl_to_h.py
  12. go_syscalls_output.cc
  13. go_syscalls_output_test.cc
  14. go_vdso_output.cc
  15. go_vdso_output_test.cc
  16. golden-test.py
  17. golden.txt
  18. json_output.cc
  19. json_output_test.cc
  20. kernel_wrappers_output.cc
  21. kernel_wrappers_output_test.cc
  22. ktrace_output.cc
  23. ktrace_output_test.cc
  24. macros.h
  25. main.cc
  26. output_util.cc
  27. output_util.h
  28. output_util_test.cc
  29. outputs.h
  30. OWNERS
  31. ownership_annotation_test.cc
  32. README.md
  33. rust_output.cc
  34. rust_output_test.cc
  35. string_util.cc
  36. string_util.h
  37. string_util_test.cc
  38. syscall_library.cc
  39. syscall_library.h
  40. syscall_library_test.cc
  41. syscall_numbers_output.cc
  42. syscall_numbers_output_test.cc
  43. test.h
  44. test_aliases.test.fidl
  45. test_go_nonblocking.test.fidl
  46. test_go_reserved_words.test.fidl
  47. test_kernel_cases.test.fidl
  48. test_kernelwrappers.test.fidl
  49. test_main.cc
  50. test_no_methods.test.fidl
  51. test_one_protocol_one_method.test.fidl
  52. test_one_protocol_two_methods.test.fidl
  53. test_one_protocol_two_methods_with_internal.test.fidl
  54. test_out_voidptr.test.fidl
  55. test_ownership_annotations.test.fidl
  56. test_pointers_and_vectors.test.fidl
  57. test_rights_specs.test.fidl
  58. test_rust_selection.test.fidl
  59. test_selection.test.fidl
  60. test_ulib_bits.test.fidl
  61. test_ulib_enums.test.fidl
  62. test_ulib_tables.test.fidl
  63. test_ulib_type_aliases.test.fidl
  64. test_various_categories.test.fidl
  65. test_vdsowrappers.test.fidl
  66. writer.cc
  67. writer.h
  68. writer_test.cc
zircon/tools/kazoo/README.md

Kazoo: Backend for fidlc for syscall definitions

Summary

kazoo is a host-side tool that operates as a backend for fidlc. In particular, Kazoo is used to process the definitions of kernel syscalls, and output various formats used by the kernel, user space, and other tools. See kazoo -h for a complete list of the output formats.

fidlc is run first to parse and interpret .fidl files, and it outputs a JSON IR representation. kazoo then processes the JSON IR.

FIDL syntax

In order to use the base FIDL syntax to express syscalls, some experimental syntax and style extensions are used. A possibly-incomplete outline of these as compared with standard FIDL syntax includes:

  • The attribute [Transport="Syscall"] must be applied to all protocols that are part of the syscall interface.

  • All .fidl files must be part of library zx (for syscalls) or library zxio.

  • Type aliases used to impart meaning. alias_workarounds.fidl includes various aliases that expand to something similar to the correct type, however Kazoo treats these specially. For example, mutable_string is used to indicate that the type is a string, but that should be treated as mutable (generally for a string that's both input and output).

  • Doc comments of the form /// Rights: ... are used by the Kazoo JSON generator, and are propagated to the documentation update script.

  • Attributes of the form [vdsocall], [const], etc. correspond to the previous similar definitions in abigen.

  • Some structs are defined in the current .fidl files, however, they're not used to generate the real Zircon headers yet. Similarly for enums, bits, etc. Only protocols are used to define the function syscall interface.

Testing

There are unittests in kazoo-test which are in the source tree next to the rest of the implementation.

To run these tests, use --with-host=zircon/tools/kazoo:tests with your fx set command, and then use fx test to run the tests, e.g.:

$ fx set core.x64 --with-host=//zircon/tools/kazoo:tests
$ fx test //zircon/tools/kazoo

This also includes a “golden”-style run, which compares the output of running kazoo on any current syscalls changes with //zircon/tools/kazoo/golden.txt. Instructions will be printed on how to update golden.txt if output differs.