Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. Comms
  5. pw_transfer
pw_transfer

Overview

Classes

class  pw::transfer::AtomicFileTransferHandler
 
class  pw::transfer::Client
 
class  pw::transfer::Handler
 
class  pw::transfer::ReadOnlyHandler
 
class  pw::transfer::WriteOnlyHandler
 
class  pw::transfer::ReadWriteHandler
 A Handler that supports both read and write transfers. More...
 
class  pw::transfer::TransferResource
 
class  pw::transfer::TransferHandlerAllocator
 
class  pw::transfer::RateEstimate
 Estimates the data transfer rate in bytes per second over elapsed wall time. More...
 
class  pw::transfer::TransferService
 
class  pw::transfer::Thread< kMaxConcurrentClientTransfers, kMaxConcurrentServerTransfers >
 

Macros

#define PW_TRANSFER_CONFIG_LOG_LEVEL   PW_LOG_LEVEL_INFO
 
#define PW_TRANSFER_CONFIG_DEBUG_CHUNKS   0
 
#define PW_TRANSFER_CONFIG_DEBUG_DATA_CHUNKS   0
 
#define PW_TRANSFER_DEFAULT_MAX_CLIENT_RETRIES   3
 
#define PW_TRANSFER_DEFAULT_MAX_SERVER_RETRIES   0
 
#define PW_TRANSFER_DEFAULT_MAX_LIFETIME_RETRIES    (static_cast<uint32_t>(PW_TRANSFER_DEFAULT_MAX_CLIENT_RETRIES) * 1000u)
 
#define PW_TRANSFER_DEFAULT_CLIENT_TIMEOUT_MS   2000
 
#define PW_TRANSFER_DEFAULT_SERVER_TIMEOUT_MS    (static_cast<uint32_t>(PW_TRANSFER_DEFAULT_CLIENT_TIMEOUT_MS) * 5u)
 
#define PW_TRANSFER_DEFAULT_INITIAL_TIMEOUT_MS    PW_TRANSFER_DEFAULT_CLIENT_TIMEOUT_MS
 
#define PW_TRANSFER_DEFAULT_EXTEND_WINDOW_DIVISOR   2
 
#define PW_TRANSFER_LOG_DEFAULT_CHUNKS_BEFORE_RATE_LIMIT   10
 
#define PW_TRANSFER_LOG_DEFAULT_RATE_PERIOD_MS   10000
 
#define PW_TRANSFER_EVENT_PROCESSING_TIMEOUT_MS    PW_TRANSFER_DEFAULT_CLIENT_TIMEOUT_MS
 

Typedefs

using pw::transfer::TransferThread = internal::TransferThread
 

Enumerations

enum class  pw::transfer::ProtocolVersion { pw::transfer::ProtocolVersion::kUnknown , pw::transfer::ProtocolVersion::kLegacy , pw::transfer::ProtocolVersion::kVersionTwo , pw::transfer::ProtocolVersion::kLatest = kVersionTwo }
 Version of the pw_transfer wire protocol. More...
 

Macro Definition Documentation

◆ PW_TRANSFER_CONFIG_DEBUG_CHUNKS

#define PW_TRANSFER_CONFIG_DEBUG_CHUNKS   0

Turns on logging of individual non-data or non-parameter chunks. Defaults to 0 (disabled). Data and parameter chunk logging has additional configuration (PW_TRANSFER_CONFIG_DEBUG_DATA_CHUNKS).

◆ PW_TRANSFER_CONFIG_DEBUG_DATA_CHUNKS

#define PW_TRANSFER_CONFIG_DEBUG_DATA_CHUNKS   0

Turns on logging of individual data and parameter chunks. Defaults to 0 (disabled). These chunks are rate-limited by PW_TRANSFER_LOG_DEFAULT_RATE_PERIOD_MS.

◆ PW_TRANSFER_CONFIG_LOG_LEVEL

#define PW_TRANSFER_CONFIG_LOG_LEVEL   PW_LOG_LEVEL_INFO

Configurable log level for the pw_transfer module. Logs below this level are omitted.

◆ PW_TRANSFER_DEFAULT_CLIENT_TIMEOUT_MS

#define PW_TRANSFER_DEFAULT_CLIENT_TIMEOUT_MS   2000

The default amount of time, in milliseconds, to wait for a chunk to arrive in a transfer client before retrying. This can later be configured per-transfer.

◆ PW_TRANSFER_DEFAULT_EXTEND_WINDOW_DIVISOR

#define PW_TRANSFER_DEFAULT_EXTEND_WINDOW_DIVISOR   2

The fractional position within a window at which a receive transfer should extend its window size to minimize the amount of time the transmitter spends blocked.

For example, a divisor of 2 will extend the window when half of the requested data has been received, a divisor of 3 will extend at a third of the window, and so on.

◆ PW_TRANSFER_DEFAULT_INITIAL_TIMEOUT_MS

#define PW_TRANSFER_DEFAULT_INITIAL_TIMEOUT_MS    PW_TRANSFER_DEFAULT_CLIENT_TIMEOUT_MS

The default amount of time, in milliseconds, for a client to wait for an initial response from the transfer server before retrying. This can later be configured per-transfer.

This is set separately from PW_TRANSFER_DEFAULT_CLIENT_TIMEOUT_MS as transfers may require additional time for resource initialization (e.g. erasing a flash region before writing to it).

◆ PW_TRANSFER_DEFAULT_MAX_CLIENT_RETRIES

#define PW_TRANSFER_DEFAULT_MAX_CLIENT_RETRIES   3

The default maximum number of times a transfer client should retry sending a chunk when no response is received. Can later be configured per-transfer when starting one.

◆ PW_TRANSFER_DEFAULT_MAX_LIFETIME_RETRIES

#define PW_TRANSFER_DEFAULT_MAX_LIFETIME_RETRIES    (static_cast<uint32_t>(PW_TRANSFER_DEFAULT_MAX_CLIENT_RETRIES) * 1000u)

The default maximum number of times a transfer should retry sending any chunk over the course of its entire lifetime.

This number should be high, particularly if long-running transfers are expected. Its purpose is to prevent transfers from getting stuck in an infinite loop.

◆ PW_TRANSFER_DEFAULT_MAX_SERVER_RETRIES

#define PW_TRANSFER_DEFAULT_MAX_SERVER_RETRIES   0

The default maximum number of times a transfer server should retry sending a chunk when no response is received.

In typical setups, retries are driven by the client, and timeouts on the server are used only to clean up resources, so this defaults to 0.

◆ PW_TRANSFER_DEFAULT_SERVER_TIMEOUT_MS

#define PW_TRANSFER_DEFAULT_SERVER_TIMEOUT_MS    (static_cast<uint32_t>(PW_TRANSFER_DEFAULT_CLIENT_TIMEOUT_MS) * 5u)

The default amount of time, in milliseconds, to wait for a chunk to arrive on the server before retrying. This can later be configured per-transfer.

◆ PW_TRANSFER_EVENT_PROCESSING_TIMEOUT_MS

#define PW_TRANSFER_EVENT_PROCESSING_TIMEOUT_MS    PW_TRANSFER_DEFAULT_CLIENT_TIMEOUT_MS

Maximum time, in milliseconds, to wait for a transfer event to be processed before dropping further queued events. In systems which can perform long-running operations to process transfer data, this can be used to prevent threads from blocking for extended periods. A value of 0 results in indefinite blocking.

◆ PW_TRANSFER_LOG_DEFAULT_CHUNKS_BEFORE_RATE_LIMIT

#define PW_TRANSFER_LOG_DEFAULT_CHUNKS_BEFORE_RATE_LIMIT   10

Number of chunks to send repetitive logs at full rate before reducing to rate-limited logging. Retransmit parameter chunks restart at this chunk count limit.

Defaults to sending the first 10 parameter logs, then reducing to one log every PW_TRANSFER_LOG_DEFAULT_RATE_PERIOD_MS.

◆ PW_TRANSFER_LOG_DEFAULT_RATE_PERIOD_MS

#define PW_TRANSFER_LOG_DEFAULT_RATE_PERIOD_MS   10000

The minimum time, in milliseconds, between repetitive logs after the rate limit has been applied (after PW_TRANSFER_LOG_DEFAULT_CHUNKS_BEFORE_RATE_LIMIT parameter chunks).

Defaults to 10000 (once every 10 seconds).

Typedef Documentation

◆ TransferThread

Non-templated transfer thread base type referenced by Client and TransferService. Derives from pw::thread::ThreadCore.

Enumeration Type Documentation

◆ ProtocolVersion

enum class pw::transfer::ProtocolVersion
strong

Version of the pw_transfer wire protocol.

Enumerator
kUnknown 

Protocol version not known or not set.

kLegacy 

The original transfer protocol, prior to transfer start/end handshakes.

kVersionTwo 

Second version of the transfer protocol. Guarantees type fields on all chunks, deprecates pending_bytes in favor of window_end_offset, splits transfer resource IDs from ephemeral session IDs, and adds a handshake to the start and end of all transfer sessions.

kLatest 

Alias to the most up-to-date version of the transfer protocol.