From 9f8214534b70aee892759473e106dbdad184b5f5 Mon Sep 17 00:00:00 2001 From: Joe-Paul Swinski Date: Mon, 17 May 2021 13:00:44 -0400 Subject: [PATCH] commented structure definitions --- common/cbuf.h | 11 ++++++----- common/rh_hash.h | 20 ++++++++++---------- inc/bplib.h | 8 ++++---- inc/bplib_store_file.h | 6 +++--- inc/bplib_store_flash.h | 42 ++++++++++++++++++++++++----------------- v6/pay.h | 8 ++++---- v6/pri.h | 34 ++++++++++++++++----------------- v6/v6.h | 14 +++++++------- 8 files changed, 76 insertions(+), 67 deletions(-) diff --git a/common/cbuf.h b/common/cbuf.h index 3766f9b3..da61b83e 100644 --- a/common/cbuf.h +++ b/common/cbuf.h @@ -28,12 +28,13 @@ TYPEDEFS ******************************************************************************/ +/* Circular Buffer Control Structure */ typedef struct { - bp_active_bundle_t* table; - bp_index_t size; - bp_index_t num_entries; - bp_val_t newest_cid; - bp_val_t oldest_cid; + bp_active_bundle_t* table; /* circular array of active bundkes */ + bp_index_t size; /* maximum (allocated) size of circular array */ + bp_index_t num_entries; /* number of bundles in the circular array */ + bp_val_t newest_cid; /* most recent custody id to be inserted into array */ + bp_val_t oldest_cid; /* oldest custody id still present in the array */ } cbuf_t; /****************************************************************************** diff --git a/common/rh_hash.h b/common/rh_hash.h index 484b3438..7f3182cb 100644 --- a/common/rh_hash.h +++ b/common/rh_hash.h @@ -29,19 +29,19 @@ ******************************************************************************/ typedef struct { - bp_active_bundle_t bundle; - bp_index_t next; // next entry in chain - bp_index_t prev; // previous entry in chain - bp_index_t after; // next entry added to hash (time ordered) - bp_index_t before; // previous entry added to hash (time ordered) + bp_active_bundle_t bundle; /* active bundle stored a this node */ + bp_index_t next; /* next entry in chain */ + bp_index_t prev; /* previous entry in chain */ + bp_index_t after; /* next entry added to hash (time ordered) */ + bp_index_t before; /* previous entry added to hash (time ordered) */ } rh_hash_node_t; typedef struct { - rh_hash_node_t* table; - bp_index_t size; - bp_index_t num_entries; - bp_index_t oldest_entry; - bp_index_t newest_entry; + rh_hash_node_t* table; /* hash table of active bundles */ + bp_index_t size; /* maximum (allocated) size of hash table */ + bp_index_t num_entries; /* number of active bundles in the hash table */ + bp_index_t oldest_entry; /* oldest bundle in the hash table */ + bp_index_t newest_entry; /* most recent bundle to be added to the hash table */ } rh_hash_t; /****************************************************************************** diff --git a/inc/bplib.h b/inc/bplib.h index e63e5777..f7e80f9a 100644 --- a/inc/bplib.h +++ b/inc/bplib.h @@ -61,7 +61,7 @@ extern "C" { #define BP_FLAG_API_ERROR 0x00080000 /* calling code incorrectly used library */ /* Handles */ -#define BP_INVALID_HANDLE (-1) /* used for integers (os locks, storage services) */ +#define BP_INVALID_HANDLE (-1) /* used for integers (os locks, storage services) */ /* Timeouts */ #define BP_PEND (-1) @@ -154,11 +154,11 @@ typedef bp_val_t bp_ipn_t; /* Address Routing */ typedef struct { - bp_ipn_t local_node; + bp_ipn_t local_node; /* IPN address used for source and custody addresses */ bp_ipn_t local_service; - bp_ipn_t destination_node; + bp_ipn_t destination_node; /* IPN address bundles are sent to */ bp_ipn_t destination_service; - bp_ipn_t report_node; + bp_ipn_t report_node; /* IPN address to send report bundles (currently not used) */ bp_ipn_t report_service; } bp_route_t; diff --git a/inc/bplib_store_file.h b/inc/bplib_store_file.h index e62c22fb..3d3d236d 100644 --- a/inc/bplib_store_file.h +++ b/inc/bplib_store_file.h @@ -33,9 +33,9 @@ extern "C" { ******************************************************************************/ typedef struct { - const char* root_path; - int cache_size; - bool flush_on_write; + const char* root_path; /* local directory used to store bundles as files */ + int cache_size; /* number of bundles to store in cache (data_cache_t) */ + bool flush_on_write; /* true: write-through cache */ } bp_file_attr_t; typedef struct { diff --git a/inc/bplib_store_flash.h b/inc/bplib_store_flash.h index 29811cd8..c885a84f 100644 --- a/inc/bplib_store_flash.h +++ b/inc/bplib_store_flash.h @@ -32,22 +32,30 @@ extern "C" { TYPEDEFS ******************************************************************************/ +/* + * Value to use to indicate an invalid flash block and/or page + */ #ifndef BP_FLASH_INVALID_INDEX #define BP_FLASH_INVALID_INDEX UINT16_MAX #endif +/* + * Type used for holding indices into flash blocks and pages; + * for example, uint8_t indicates that only 255 blocks or pages + * are accessible. + */ #ifndef BP_FLASH_INDEX_TYPE #define BP_FLASH_INDEX_TYPE uint16_t #endif +/* + * The number of flash based storage service control structures to + * statically allocate + */ #ifndef FLASH_MAX_STORES #define FLASH_MAX_STORES 24 #endif -#ifndef FLASH_MAX_PAGES_PER_BLOCK -#define FLASH_MAX_PAGES_PER_BLOCK 128 -#endif - /****************************************************************************** TYPEDEFS ******************************************************************************/ @@ -66,25 +74,25 @@ typedef int (*bp_flash_block_is_bad_t) (bp_flash_index_t block); typedef int (*bp_flash_physical_block_t) (bp_flash_index_t logblk); typedef struct { - bp_flash_index_t num_blocks; - bp_flash_index_t pages_per_block; - int page_size; /* bytes */ - bp_flash_page_read_t read; - bp_flash_page_write_t write; - bp_flash_block_erase_t erase; - bp_flash_block_is_bad_t isbad; - bp_flash_physical_block_t phyblk; + bp_flash_index_t num_blocks; /* number of blocks available in flash device */ + bp_flash_index_t pages_per_block; /* number of pages per block available in flash device */ + int page_size; /* size of page in bytes */ + bp_flash_page_read_t read; /* function pointer to read page */ + bp_flash_page_write_t write; /* function pointer to write page */ + bp_flash_block_erase_t erase; /* function pointer to erase block */ + bp_flash_block_is_bad_t isbad; /* functino pointer to check if block bad */ + bp_flash_physical_block_t phyblk; /* function pointer to convert between logical and physical block addresses */ } bp_flash_driver_t; typedef struct { - int num_free_blocks; - int num_used_blocks; - int num_fail_blocks; - int error_count; + int num_free_blocks; /* number of free blocks available to driver to store bundles in */ + int num_used_blocks; /* number of blocks currently used by the driver */ + int num_fail_blocks; /* number of blocks that have been removed from the free list due to errors */ + int error_count; /* number of flash operations that have returned an error */ } bp_flash_stats_t; typedef struct { - int max_data_size; /* max size of data being cached */ + int max_data_size; /* max size of data stored, must exceed page size */ } bp_flash_attr_t; /****************************************************************************** diff --git a/v6/pay.h b/v6/pay.h index 371c1774..ea437bed 100644 --- a/v6/pay.h +++ b/v6/pay.h @@ -30,10 +30,10 @@ ******************************************************************************/ typedef struct { - bp_field_t bf; - bp_field_t blklen; - uint8_t* payptr; - int paysize; + bp_field_t bf; /* block flags */ + bp_field_t blklen; /* block length */ + uint8_t* payptr; /* pointer to payload */ + int paysize; /* size in bytes of payload */ } bp_blk_pay_t; /****************************************************************************** diff --git a/v6/pri.h b/v6/pri.h index bd532dff..2f831c7a 100644 --- a/v6/pri.h +++ b/v6/pri.h @@ -32,23 +32,23 @@ /* Bundle Primary Block */ typedef struct { /* field data */ - uint8_t version; - bp_field_t pcf; - bp_field_t blklen; - bp_field_t dstnode; - bp_field_t dstserv; - bp_field_t srcnode; - bp_field_t srcserv; - bp_field_t rptnode; - bp_field_t rptserv; - bp_field_t cstnode; - bp_field_t cstserv; - bp_field_t createsec; - bp_field_t createseq; - bp_field_t lifetime; - bp_field_t dictlen; - bp_field_t fragoffset; - bp_field_t paylen; + uint8_t version; /* bundle protocol version */ + bp_field_t pcf; /* process control flags */ + bp_field_t blklen; /* block length */ + bp_field_t dstnode; /* destination node */ + bp_field_t dstserv; /* destination service */ + bp_field_t srcnode; /* source node */ + bp_field_t srcserv; /* source service */ + bp_field_t rptnode; /* report to node */ + bp_field_t rptserv; /* report to service */ + bp_field_t cstnode; /* custody node */ + bp_field_t cstserv; /* custody service */ + bp_field_t createsec; /* creation timestamp - seconds */ + bp_field_t createseq; /* creation timestamp - sequence number */ + bp_field_t lifetime; /* bundle lifetime (seconds since J2000) */ + bp_field_t dictlen; /* dictionary length in bytes */ + bp_field_t fragoffset; /* payload fragment offset in bytes */ + bp_field_t paylen; /* payload length in bytes */ /* meta information */ bool is_admin_rec; /* 0: not admin, 1: is admin */ bool is_frag; /* 0: is not a fragment, 1: is a fragment */ diff --git a/v6/v6.h b/v6/v6.h index afa07629..81cc3823 100644 --- a/v6/v6.h +++ b/v6/v6.h @@ -49,19 +49,19 @@ #define BP_BIB_INTEGRITY_SIGNATURE 5 /* Bundle Creation Time Handling */ -#define BP_TTL_CREATION_TIME 0 /* time-to-live extension block may be used */ -#define BP_UNKNOWN_CREATION_TIME 1 /* unreliable time source */ -#define BP_BEST_EFFORT_LIFETIME 1576800000; /* 50 years; ground systems using 'int' type for time have maximum of 68 years */ +#define BP_TTL_CREATION_TIME 0 /* time-to-live extension block may be used */ +#define BP_UNKNOWN_CREATION_TIME 1 /* unreliable time source */ +#define BP_BEST_EFFORT_LIFETIME 1576800000 /* 50 years; ground systems using 'int' type for time have maximum of 68 years */ /* Record Type Definitions */ -#define BP_STAT_REC_TYPE 0x10 /* Status Report */ -#define BP_CS_REC_TYPE 0x20 /* Custody Signal */ -#define BP_ACS_REC_TYPE 0x40 /* Aggregate Custody Signal */ +#define BP_STAT_REC_TYPE 0x10 /* Status Report */ +#define BP_CS_REC_TYPE 0x20 /* Custody Signal */ +#define BP_ACS_REC_TYPE 0x40 /* Aggregate Custody Signal */ /* Aggregate Custody Signal Definitions */ #define BP_ACS_REC_TYPE_INDEX 0 #define BP_ACS_REC_STATUS_INDEX 1 -#define BP_ACS_ACK_MASK 0x80 /* if set, then custody successfully transfered */ +#define BP_ACS_ACK_MASK 0x80 /* if set, then custody successfully transfered */ /* Processing Control Flags */ #define BP_PCF_FRAGMENT_MASK 0x000001 /* bundle is a fragement */