dooocs

src/dest.rs

@@ -1,3 +1,10 @@
+//! CFDP Destination Entity Module
+//!
+//! The [DestinationHandler] is the primary component of this module which converts the PDUs sent
+//! from a remote source entity back to a file. A file copy operation on the receiver side
+//! is started with the reception of a Metadata PDU, for example one generated by the
+//! [spacepackets::cfdp::pdu::metadata::MetadataPduCreator]. After that, file packet PDUs, for
+//! example generated with the [spacepackets::cfdp::pdu::file_data] module.
 use crate::{user::TransactionFinishedParams, DummyPduProvider, GenericSendError, PduProvider};
 use core::str::{from_utf8, from_utf8_unchecked, Utf8Error};
 

src/lib.rs

@@ -1,5 +1,20 @@
-//! This module contains the implementation of the CFDP high level abstractions as specified in
+//! This module contains the implementation of the CCSDS File Delivery Protocol (CFDP) high level
-//! CCSDS 727.0-B-5.
+//! abstractions as specified in CCSDS 727.0-B-5.
+//!
+//! The basic idea of CFDP is to convert files of any size into a stream of packets called packet
+//! data units (PDU). CFPD has an unacknowledged and acknowledged mode, with the option to request
+//! a transaction closure for the unacknowledged mode. Using the unacknowledged mode with no
+//! transaction closure is applicable for simplex communication paths, while the unacknowledged
+//! mode with closure is the easiest way to get a confirmation of a successful file transfer,
+//! including a CRC check on the remote side to verify file int egrity. The acknowledged mode is
+//! the most complex mode which includes multiple mechanism to ensure succesfull packet transaction
+//! even for unreliable connections, including lost segment detection. As such, it can be compared
+//! to a specialized TCP for file transfers with remote systems.
+//!
+//! The core  of these high-level components are the [crate::dest::DestinationHandler] and the
+//! [crate::source::SourceHandler] component. These model the CFDP destination and source entity
+//! respectively. You can find high-level and API documentation for both handlers in the respective
+//! [crate::dest] and [crate::source] module.
 #![no_std]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #[cfg(feature = "alloc")]

src/source.rs

@@ -1,3 +1,41 @@
+//! # CFDP Source Entity Module
+//!
+//! The [SourceHandler] is the primary component of this module which converts a
+//! [ReadablePutRequest] into all packet data units (PDUs) which need to be sent to a remote
+//! CFDP entity to perform a File Copy operation to a remote entity.
+//!
+//! The source entity allows freedom communication by using a user-provided [PduSendProvider]
+//! to send all generated PDUs. It should be noted that for regular file transfers, each
+//! [SourceHandler::state_machine] call will map to one generated file data PDU. This allows
+//! flow control for the user of the state machine.
+//!
+//! The [SourceHandler::state_machine] will generally perform the following steps after a valid
+//! put request was received through the [SourceHandler::put_request] method:
+//!
+//!  1. Generate the Metadata PDU to be sent to a remote CFDP entity. You can use the
+//!    [spacepackets::cfdp::pdu::metadata::MetadataPduReader] to inspect the generated PDU.
+//!  2. Generate all File Data PDUs to be sent to a remote CFDP entity if applicable (file not
+//!    empty). The PDU(s) can be inspected using the [spacepackets::cfdp::pdu::file_data::FileDataPdu] reader.
+//!  3. Generate an EOF PDU to be sent to a remote CFDP entity. The PDU can be inspected using
+//!    the [spacepackets::cfdp::pdu::eof::EofPdu] reader.
+//!
+//! If this is an unacknowledged transfer with no transaction closure, the file transfer will be
+//! done after these steps. In any other case:
+//!
+//! ### Unacknowledged transfer with requested closure
+//!
+//!  4. A Finished PDU will be awaited, for example one generated using
+//!    [spacepackets::cfdp::pdu::finished::FinishedPduCreator].
+//!
+//! ### Acknowledged transfer (*not implemented yet*)
+//!
+//!  4. A EOF ACK packet will be awaited, for example one generated using
+//!    [spacepackets::cfdp::pdu::ack::AckPdu].
+//!  5. A Finished PDU will be awaited, for example one generated using
+//!    [spacepackets::cfdp::pdu::finished::FinishedPduCreator].
+//!  6. A finished PDU ACK packet will be generated to be sent to the remote CFDP entity.
+//!    The [spacepackets::cfdp::pdu::finished::FinishedPduReader] can be used to inspect the
+//!    generated PDU.
 use core::{cell::RefCell, ops::ControlFlow, str::Utf8Error};
 
 use spacepackets::{