Browse Source

changes to documentation for sync generation (not yet complete)

doxygen_doc
parent
commit
4e772ae3e7
5 changed files with 339 additions and 108 deletions
  1. +4
    -3
      engine_doxygen.conf
  2. +54
    -4
      sync/gen_actions.ysl2
  3. +68
    -40
      sync/gen_codec.ysl2
  4. +35
    -2
      sync/gen_message_func.ysl2
  5. +178
    -59
      sync/gen_statemachine.ysl2

+ 4
- 3
engine_doxygen.conf View File

@ -51,14 +51,14 @@ PROJECT_BRIEF =
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory.
PROJECT_LOGO = /Users/krista/src/pEpEngine/doc/logo.png
PROJECT_LOGO = ./doc/logo.png
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.
OUTPUT_DIRECTORY = /Users/krista/src/pEpEngine/doc/doxygen
OUTPUT_DIRECTORY = ./doc/doxygen
# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
# directories (in 2 levels) under the output directory of each output format and
@ -263,7 +263,8 @@ TAB_SIZE = 4
ALIASES = "license=@par License:^^" \
"copyleft=@par Copyleft:^^" \
"ownership=@par Ownership^^"
"ownership=@par Ownership^^" \
"generated=@par Generated^^"
# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
# only. Doxygen will then generate output that is more tailored for C. For


+ 54
- 4
sync/gen_actions.ysl2 View File

@ -28,8 +28,14 @@ tstylesheet {
template "/protocol" {
document "generated/{@name}_actions.c", "text" {
||
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file «@name»_actions.c
* @brief Implementation of «@name» conditions, actions, and timeout handlers defined in «@name»_impl.h,
* with supporting static (internal) functions
* @generated from ../sync/gen_actions.ysl2
*
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "pEp_internal.h"
#include "map_asn1.h"
@ -37,6 +43,20 @@ tstylesheet {
#include "«@name»_impl.h"
`` for "fsm" | #include "«@name»_fsm.h"
/**
* <!-- _TID_greater() -->
*
* @internal
*
* @brief Compare two traffic identifiers and see if the first is greater than the second
*
* @param[in] t1 pointer to the first TID
* @param[in] t2 pointer to the second TID
*
* @retval true if t2 is NULL and t1 is not, or the size of t1 is greater than t2, or
* the first non-matching byte of t1 is greater than that of t2
* false otherwise
*/
static bool _TID_greater(TID_t *t1, TID_t *t2)
{
assert(t1 && t2);
@ -53,6 +73,20 @@ tstylesheet {
return memcmp(t1->buf, t2->buf, t1->size) > 0;
}
/**
* <!-- _same_identity() -->
*
* @internal
*
* @brief Determine if two identity refer to the same identity (by comparing the unique identifier
* of user_id + address)
*
* @param[in] ident1 pointer to the first identity
* @param[in] ident2 pointer to the second identity
*
* @retval true if user_id and address match on both identities
* false otherwise
*/
static bool _same_identity(pEp_identity *ident1, pEp_identity *ident2)
{
if (!(ident1 && ident1->user_id && ident1->address && ident2 && ident2->user_id && ident2->address))
@ -62,10 +96,26 @@ tstylesheet {
&& strcmp(ident1->address, ident2->address) == 0;
}
/**
* <!-- _have_identity_in() -->
*
* @internal
*
* @brief Given an identity list and an identity, determine if there is an identity in
* the list that refers to the same identity as the identity struct.
*
* @param[in] il pointer to the identity list
* @param[in] ident pointer to the identity to search for
* @param[out] found true if an identity with matching unique identifiers is in the list, else false
*
* @retval PEP_ILLEGAL_VALUE any of the input pointers are NULL
* PEP_OUT_OF_MEMORY if memory problems occur
* PEP_STATUS_OK otherwise
*/
static PEP_STATUS _have_identity_in(identity_list *il, pEp_identity *ident, bool *found)
{
assert(il && ident);
if (!(il && ident))
assert(il && ident && found);
if (!(il && ident && found))
return PEP_ILLEGAL_VALUE;
bool _found = false;


+ 68
- 40
sync/gen_codec.ysl2 View File

@ -15,8 +15,16 @@ tstylesheet {
template "/protocol" {
document "generated/{yml:lcase(@name)}_codec.h", "text"
||
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file «@name»_codec.h
* @brief Definitions for «@name» encode and decode functions which transform message payloads to
* and from PER-encoded data, and XER text to and from PER
* @generated from ../sync/gen_codec.ysl2
*
* @see https://www.itu.int/en/ITU-T/asn1/Pages/introduction.aspx
*
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#pragma once
@ -31,33 +39,38 @@ tstylesheet {
struct «@name»;
// decode_«@name»_message() - decode PER encoded «@name» message
//
// parameters:
// data (in) PER encoded data
// size (in) size of PER encoded data
// msg (out) «@name» message
//
// caveat:
// msg goes into the ownership of the caller
/**
* <!-- decode_«@name»_message() -->
*
* @brief decode PER encoded «@name» message
*
* @param[in] data PER encoded data
* @param[in] size size of PER encoded data
* @param[out] msg decoded «@name» message
*
* @retval status
*
* @ownership msg goes into the ownership of the caller
*/
DYNAMIC_API PEP_STATUS decode_«@name»_message(
const char *data,
size_t size,
struct «@name» **msg
);
// encode_«@name»_message() - encode «@name» message into PER encoded data
//
// parameters:
// msg (in) «@name» message
// data (out) PER encoded data
// size (out) size of PER encoded data
//
// caveat:
// data goes to the ownership of the caller
/**
* <!-- encode_«@name»_message() -->
*
* @brief decode PER encoded «@name» message
*
* @param[in] msg «@name» message to encode
* @param[out] data PER encoded data
* @param[out] size size of PER encoded data
*
* @retval status
*
* @ownership msg goes into the ownership of the caller
*/
DYNAMIC_API PEP_STATUS encode_«@name»_message(
struct «@name» *msg,
char **data,
@ -65,27 +78,34 @@ tstylesheet {
);
// PER_to_XER_«@name»_msg() - decode «@name» message from PER into XER
//
// parameters:
// data (in) PER encoded data
// size (in) size of PER encoded data
// text (out) XER text of the same «@name» message
/**
* <!-- PER_to_XER_«@name»_msg() -->
*
* @brief decode «@name» message from PER into XER
*
* @param[in] data PER encoded data
* @param[in] size size of PER encoded data
* @param[out] text XER text of the same «@name» message
*
* @retval status
*/
DYNAMIC_API PEP_STATUS PER_to_XER_«@name»_msg(
const char *data,
size_t size,
char **text
);
// XER_to_PER_«@name»_msg() - encode «@name» message from XER into PER
//
// parameters:
// text (in) string with XER text of the «@name» message
// data (out) PER encoded data
// size (out) size of PER encoded data
/**
* <!-- XER_to_PER_«@name»_msg() -->
*
* @brief encode «@name» message from XER into PER
*
* @param[in] text string text with XER text of the «@name» message
* @param[out] data PER encoded data
* @param[out] size size of PER encoded data
*
* @retval status
*/
DYNAMIC_API PEP_STATUS XER_to_PER_«@name»_msg(
const char *text,
char **data,
@ -100,8 +120,16 @@ tstylesheet {
||
document "generated/{yml:lcase(@name)}_codec.c", "text"
||
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file «@name»_codec.c
* @brief Implementation for «@name» encode and decode functions which transform message payloads to
* and from PER-encoded data, and XER text to and from PER
* @generated from ../sync/gen_codec.ysl2
*
* @see https://www.itu.int/en/ITU-T/asn1/Pages/introduction.aspx
*
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "platform.h"


+ 35
- 2
sync/gen_message_func.ysl2 View File

@ -22,8 +22,13 @@ template "/" {
template "protocol", mode=header
document "generated/{@name}_func.h", "text"
||
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file «@name»_func.h
* @brief States and functions for the «@name» protocol.
* @generated from ../sync/gen_message_func.ysl2
*
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#pragma once
@ -72,11 +77,39 @@ struct «@name»_state_s {
`` apply "fsm", mode=state
};
/**
* <!-- free_«@name»_state() -->
*
* @brief free and reset all «@name» state associated with this session
*
* @param[in] session the session
*
*/
void free_«@name»_state(PEP_SESSION session);
// functions for protocol «@name»
/**
* <!-- new_«@name»_message() -->
*
* @brief create a new «@name» message of the indicated type
*
* @param[in] fsm the state machine
* @param[in] message_type the type of «@name» message to be created
*
* @return ???
*
*/
«@name»_t *new_«@name»_message(«@name»_PR fsm, int message_type);
/**
* <!-- free_«@name»_message() -->
*
* @brief free a «@name» message struct
*
* @param[in] msg the desired message
*
*/
void free_«@name»_message(«@name»_t *msg);
PEP_STATUS update_«@name»_state(PEP_SESSION session, «@name»_t *msg,


+ 178
- 59
sync/gen_statemachine.ysl2 View File

@ -16,8 +16,13 @@ tstylesheet {
template "/protocol" {
document "generated/{@name}_event.h", "text"
||
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file «@name»_event.h
* @brief Structures and functions for «@name» events.
* @generated from ../sync/gen_statemachine.ysl2
*
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#pragma once
@ -43,31 +48,31 @@ tstylesheet {
identity_list *own_identities;
} «@name»_event_t;
// new_«@name»_event() - allocate a new «@name»_event
//
// parameters:
// fsm (in) finite state machine the event is for
// event (in) event or None
// msg (in) message to compute event from
//
// return value:
// pointer to new event or NULL in case of failure
//
// caveat:
// event must be valid for fsm or None
// in case msg is given event will be calculated out of message
/**
* <!-- new_«@name»_event() -->
*
* @brief allocate a new «@name»_event
*
* @param[in] fsm finite state machine the event is for
* @param[in] event event or None
* @param[in] msg message to compute event from
*
* @retval pointer to new event
* @retval NULL in case of failure
*
*/
DYNAMIC_API «@name»_event_t *new_«@name»_event(«yml:ucase(@name)»_PR fsm, int event, «yml:ucase(@name)» *msg);
#define «yml:ucase(@name)»_TIMEOUT_EVENT new_«@name»_event(«@name»_PR_NOTHING, 0, NULL);
// free_«@name»_event() - free memory occupied by event
//
// parameters:
// ev (in) event to free
/**
* <!-- free_«@name»_event() -->
*
* @brief free memory occupied by event
*
* @param[in] ev event to free
*
*/
DYNAMIC_API void free_«@name»_event(«@name»_event_t *ev);
@ -79,8 +84,14 @@ tstylesheet {
document "generated/{@name}_event.c", "text"
||
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file «@name»_event.c
* @brief Allocation, fsm drivers, and handling for «@name» events.
* @generated from ../sync/gen_statemachine.ysl2
*
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "platform.h"
@ -128,8 +139,13 @@ tstylesheet {
document "generated/{@name}_impl.h", "text" {
||
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file «@name»_impl.h
* @brief «@name» protocol implementation declarations
* @generated from ../sync/gen_statemachine.ysl2
*
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#pragma once
@ -145,68 +161,156 @@ tstylesheet {
extern "C" {
#endif
/////////////////////////////////////////////////////////////////////
// conditions
/////////////////////////////////////////////////////////////////////
||
for "func:distinctName(*//condition)"
| PEP_STATUS «@name»(PEP_SESSION session, bool *result);
for "func:distinctName(*//condition)" {
| /**
| * @brief Evaluate condition: Is «@name» true?
| * @param[in] session the session
| * @param[out] result true if «@name», else false
| * @retval status
| */
| PEP_STATUS «@name»(PEP_SESSION session, bool * result);
}
||
/////////////////////////////////////////////////////////////////////
// actions
/////////////////////////////////////////////////////////////////////
||
for "func:distinctName(*//action)"
for "func:distinctName(*//action)" {
| /**
| * @brief Action: Do «@name»
| * @param[in] session the session
| * @retval status
| */
| PEP_STATUS «@name»(PEP_SESSION session);
}
||
// timeout handler
/////////////////////////////////////////////////////////////////////
// timeout handlers
/////////////////////////////////////////////////////////////////////
||
for "fsm[@threshold > 0]"
for "fsm[@threshold > 0]" {
| /**
| * <!-- «@name»TimeoutHandler() -->
| *
| * @brief Handle timeouts for «@name» state machine
| *
| * @param[in] session the session
| * @retval status
| */
| PEP_STATUS «@name»TimeoutHandler(PEP_SESSION session);
}
||
// send message about an event to communication partners using state
/////////////////////////////////////////////////////////////////////
// «@name» state machine driver, message sending, and event receipt
/////////////////////////////////////////////////////////////////////
/**
* <!-- send_«@name»_message() -->
*
* @brief send message about «@name» event to communication partners using state
*
* @param[in] session the session
* @param[in] fsm the finite state machine from which to get state
* @param[in] message_type type of message to send
*
* @retval status of message send
*
*/
PEP_STATUS send_«@name»_message(
PEP_SESSION session,
«@name»_PR fsm,
int message_type
);
// receive message and store it in state
PEP_SESSION session,
«@name»_PR fsm,
int message_type
);
/**
* <!-- recv_«@name»_event() -->
*
* @brief receive «@name» message and store it in state
*
* @param[in] session the session
* @param[in] ev the event to process
*
* @retval status of event processing/storage
*
*/
PEP_STATUS recv_«@name»_event(
PEP_SESSION session,
«@name»_event_t *ev
);
// state machine driver
// if fsm or event set to 0 use fields in src if present
/**
* <!-- «@name»_driver() -->
*
* @brief «@name» state machine driver
*
* @param[in] session the session
* @param[in] fsm finite state machine to drive
* @param[in] ev the event to process???
*
* @retval ???
*
* @note if fsm or event set to 0 use fields in src if present
*
*/
PEP_STATUS «@name»_driver(
PEP_SESSION session,
«@name»_PR fsm,
int event
);
// API being used by the engine internally
// call this if you need to signal an external event
// caveat: the ownership of own_identities goes to the callee
/////////////////////////////////////////////////////////////////////////////
// API used by the engine internally //
/////////////////////////////////////////////////////////////////////////////
/**
* <!-- signal_«@name»_event() -->
*
* @brief Internal engine API: call this if you need to signal an external «@name» event
*
* @param[in] session the session
* @param[in] fsm finite state machine
* @param[in] event event type
* @param[out] own_identities list of own identities
*
* @retval status
*
* @ownership the ownership of own_identities goes to the callee
*
*/
PEP_STATUS signal_«@name»_event(
PEP_SESSION session,
PEP_SESSION session,
«@name»_PR fsm,
int event,
identity_list *own_identities
);
// call this if you are a transport and are receiving
// a «@name» message
/**
* <!-- signal_«@name»_message() -->
*
* @brief Internal engine API: to be called by transports receiving a «@name» message
*
* @param[in] session the session
* @param[in] rating rating of the decrypted «@name» message
* @param[out] data payload of «@name» message
* @param[out] from identity of the message sender
* @param[out] fpr fingerprint of the sender key used to sign the message
*
* @retval status
*
*/
PEP_STATUS signal_«@name»_message(
PEP_SESSION session,
PEP_SESSION session,
PEP_rating rating,
const char *data,
size_t size,
@ -223,8 +327,13 @@ tstylesheet {
document "generated/{@name}_impl.c", "text" {
||
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file «@name»_impl.c
* @brief «@name» protocol implementation: driver, event handling, message signalling/sending/receipt, etc.
* @generated from ../sync/gen_statemachine.ysl2
*
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "«@name»_impl.h"
#include "pEp_internal.h"
@ -1236,8 +1345,13 @@ tstylesheet {
template "fsm", mode=gen {
document "generated/{@name}_fsm.h", "text" {
||
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file «@name»_fsm.h
* @brief Finite state machine states, definitions, and structs for the «@name» protocol.
* @generated from ../sync/gen_statemachine.ysl2
*
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#pragma once
@ -1308,8 +1422,13 @@ tstylesheet {
document "generated/{@name}_fsm.c", "text" {
||
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file «@name»_fsm.c
* @brief Finite state machine implementation for the «@name» protocol.
* @generated from ../sync/gen_statemachine.ysl2
*
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "«@name»_fsm.h"
#include <stdlib.h>


Loading…
Cancel
Save