Skip to content

Commit

Permalink
Update documentation for rust generated code
Browse files Browse the repository at this point in the history
  • Loading branch information
@hchataing
hchataing committed May 1, 2024
1 parent 5a64e66 commit 2b354fc
Showing 1 changed file with 116 additions and 9 deletions.
125 changes: 116 additions & 9 deletions doc/rust-generated-code-guide.rst
View file
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> |
+---------------------------------------+---------------------------------------------------------------+

0 comments on commit 2b354fc

Please sign in to comment.