Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite the Rust generator #96

Merged
merged 2 commits into from
May 13, 2024
Merged

Rewrite the Rust generator #96

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5a64e66
Refactor the rust generator
hchataing Mar 30, 2024
2b354fc
Update documentation for rust generated code
hchataing May 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/workflows/build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,9 @@ jobs:
- name: Run Rust generator tests
run: pdl-compiler/tests/run_rust_generator_tests.sh

- name: Run legacy Rust generator tests
run: pdl-compiler/tests/run_rust_legacy_generator_tests.sh

- name: Run CXX generator tests
run: pdl-compiler/tests/run_cxx_generator_tests.sh

Expand All @@ -99,3 +102,6 @@ jobs:

- name: Compile Rust generated files
run: pdl-compiler/tests/compile_rust_generated_files.sh

- name: Compile legacy Rust generated files
run: pdl-compiler/tests/compile_rust_legacy_generated_files.sh
125 changes: 116 additions & 9 deletions doc/rust-generated-code-guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,12 @@ Language bindings
This section contains the generated rust bindings for language constructs that
are stabilized.

Runtime
^^^^^^^
.. warning::
PDL authorizes the use of rust keywords as identifier. Keyword identifiers
are generated as raw identifiers, e.g. `type` is generated as `r#type`.

Enum declarations
^^^^^^^^^^^^^^^^^

Private prevents users from creating arbitrary scalar values in situations where
the value needs to be validated. Users can freely deref the value, but only the
Expand All @@ -47,13 +51,6 @@ backend may create it.

impl<T> std::ops::Deref for Private<T> { .. }

.. warning::
PDL authorizes the use of rust keywords as identifier. Keyword identifiers
are generated as raw identifiers, e.g. `type` is generated as `r#type`.

Enum declarations
^^^^^^^^^^^^^^^^^

+---------------------------------------+---------------------------------------------------------------+
| :: | .. sourcecode:: rust |
| | |
Expand Down Expand Up @@ -113,3 +110,113 @@ Enum declarations
| | impl From<TestEnum> for i32 { .. } |
| | impl From<TestEnum> for i64 { .. } |
+---------------------------------------+---------------------------------------------------------------+

Packet declarations
^^^^^^^^^^^^^^^^^^^

Generated packet representations will all implement the `Packet` trait from
the `pdl_runtime` crate, which declares methods for parsing and serializing
packets:

.. sourcecode:: rust

pub trait Packet: Sized {
fn decode(buf: &[u8]) -> Result<(Self, &[u8]), DecodeError>;
fn encode(&self, buf: &mut impl BufMut) -> Result<(), EncodeError>;
fn encoded_len(&self) -> usize;
}

Additional methods are generated depending on characteristics of the PDL
declaration (see the table below).

* derived packet declarations implement `decode_partial` (resp. `encode_partial`).
These methods will decode (resp. encode) fields from the parent payload.

* packets with child declarations implement `specialize`. This method will
attempt to decode one of the child packets from the input packet based on the
constraints that are available.

+---------------------------------------+---------------------------------------------------------------+
| :: | .. sourcecode:: rust |
| | |
| packet Parent { | #[device(Debug, Clone, PartialEq, Eq)] |
| a:8, | struct TestPacket { |
| _paylolad_, | a: u8, |
| } | b: TestEnum, |
| | payload: Vec<u8>, |
| packet TestPacket : Parent { | } |
| b: TestEnum, | |
| _payload_, | impl TestPacket { |
| } | pub fn a(&self) -> u8 { .. } |
| | pub fn b(&self) -> TestEnum { .. } |
| | pub fn payload(&self) -> &[u8] { .. } |
| | |
| | pub fn encode_partial(&self, buf: &mut impl BufMut) |
| | -> Result<(), EncodeError> { .. } |
| | |
| | pub fn decode_partial(parent: &Parent) |
| | -> Result<Self, DecoderError { .. } |
| | } |
| | |
| | impl pdl_runtime::Packet for TestPacket { .. } |
| | impl TryFrom<&TestPacket> for Bytes { .. } |
| | impl TryFrom<&TestPacket> for Vec<u8> { .. } |
+---------------------------------------+---------------------------------------------------------------+
| :: | .. sourcecode:: rust |
| | |
| packet TestPacket { | #[derive(Debug, Clone, PartialEq, Eq)] |
| a: 8, | struct TestPacket { |
| _payload_, | a: u8, |
| } | payload: Vec<u8>, |
| | } |
| packet Child1 : TestPacket { | |
| .. | #[derive(Debug, Clone, PartialEq, Eq)] |
| } | struct TestPacketChild { |
| | Child1(Child1), |
| packet Child2 : TestPacket { | Child2(Child2), |
| .. | None, |
| } | } |
| | |
| | impl TestPacket { |
| | pub fn a(&self) -> u8 { .. } |
| | pub fn payload(&self) -> &[u8] { .. } |
| | pub fn specialize(&self) |
| | -> Result<TestPacketChild, DecodeError> { .. } |
| | } |
| | |
| | impl pdl_runtime::Packet for TestPacket { .. } |
| | impl TryFrom<&TestPacket> for Bytes { .. } |
| | impl TryFrom<&TestPacket> for Vec<u8> { .. } |
+---------------------------------------+---------------------------------------------------------------+

Field declarations
^^^^^^^^^^^^^^^^^^

+---------------------------------------+---------------------------------------------------------------+
| :: | .. sourcecode:: rust |
| | |
| a: 8 | a: u8 |
| b: 24 | b: u32 |
+---------------------------------------+---------------------------------------------------------------+
| :: | .. sourcecode:: rust |
| | |
| a: TestEnum, | a: TestEnum |
| b: TestStruct | b: TestStruct |
+---------------------------------------+---------------------------------------------------------------+
| :: | .. sourcecode:: rust |
| | |
| a: 8[], | a: Vec<u8> |
| b: 16[128], | b: [u16; 128] |
| c: TestEnum[], | c: Vec<TestEnum> |
| d: TestStruct[] | d: Vec<TestStruct> |
+---------------------------------------+---------------------------------------------------------------+
| :: | .. sourcecode:: rust |
| | |
| a: 8 if c_a = 1, | a: Option<u8> |
| b: TestEnum if c_b = 1, | b: Option<TestEnum> |
| c: TestStruct if c_c = 1, | c: Option<TestStruct> |
+---------------------------------------+---------------------------------------------------------------+
| :: | .. sourcecode:: rust |
| | |
| _payload_, | payload: Vec<u8> |
+---------------------------------------+---------------------------------------------------------------+
1 change: 1 addition & 0 deletions pdl-compiler/src/backends.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,6 @@

pub mod intermediate;
pub mod json;
pub mod rust;
pub mod rust_legacy;
pub mod rust_no_allocation;
Loading
Loading