1# Packet Description Language (PDL)
2
3[![Crate](https://img.shields.io/crates/v/pdl-compiler?style=flat-square)](https://crates.io/crates/pdl-compiler)
4[![Build workflow](https://img.shields.io/github/actions/workflow/status/google/pdl/build.yml?style=flat-square)](https://github.com/google/pdl/actions/workflows/build.yml?query=branch%3Amain)
5[![GitHub contributors](https://img.shields.io/github/contributors/google/pdl?style=flat-square)](https://github.com/google/pdl/graphs/contributors)
6[![GitHub stars](https://img.shields.io/github/stars/google/pdl?style=flat-square)](https://github.com/google/pdl/stargazers)
7
8PDL is a domain specific language for writing the definition of binary protocol
9packets. Parsing and validating packets from raw bytes is tedious and error
10prone in any language. PDL generates memory safe and tailored backends for
11multiple target languages:
12
13    - Rust
14    - C++
15    - Python
16
17Historically PDL was developed as part of the Android Bluetooth stack
18([bluetooth_packetgen](https://cs.android.com/android/platform/superproject/+/master:packages/modules/Bluetooth/system/gd/packet/))
19as a way to generate the parser and serializer for Bluetooth packets, and
20reduce the number of memory safety issues that come with manipulating
21and validating raw data.
22
23## How to use PDL
24
251. Write the protocol definition
261. `cargo run my-protocol.pdl --output-format rust > my-protocol.rs`
27
28Language specific instructions are provided for all supported backends:
29
301. [Rust generated code guide](doc/rust-generated-code-guide.rst)
311. [Python generated code guide](doc/python-generated-code-guide.rst)
321. [C++ generated code guide](doc/cxx-generated-code-guide.rst)
33
34## Supported Features
35
36[Full reference documentation](doc/reference.md)
37- Scalar values
38- Enumerators
39- Arrays
40- Optional fields
41- Nested packets
42- Conditional packet derivation
43- Custom field definitions
44
45## Similar projects
46
47- [Kaitai](https://kaitai.io)
48- [Emboss](https://github.com/google/emboss)
49- [P4](https://p4.org/p4-spec/docs/P4-16-v1.0.0-spec.html)
50