From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail04.ics.ntt-tx.co.jp (mail05.ics.ntt-tx.co.jp [210.232.35.69]) by dpdk.org (Postfix) with ESMTP id 4022C1B828 for ; Thu, 8 Feb 2018 06:56:05 +0100 (CET) Received: from gwchk03.silk.ntt-tx.co.jp (gwchk03.silk.ntt-tx.co.jp [10.107.0.111]) by mail04.ics.ntt-tx.co.jp (unknown) with ESMTP id w185u4pl004455 for unknown; Thu, 8 Feb 2018 14:56:04 +0900 Received: (from root@localhost) by gwchk03.silk.ntt-tx.co.jp (unknown) id w185u4h4009873 for unknown; Thu, 8 Feb 2018 14:56:04 +0900 Received: from gwchk.silk.ntt-tx.co.jp [10.107.0.110] by gwchk03.silk.ntt-tx.co.jp with ESMTP id QAA09872; Thu, 8 Feb 2018 14:56:04 +0900 Received: from imss03.silk.ntt-tx.co.jp (localhost [127.0.0.1]) by imss03.silk.ntt-tx.co.jp (unknown) with ESMTP id w185u326011268 for unknown; Thu, 8 Feb 2018 14:56:03 +0900 Received: from mgate02.silk.ntt-tx.co.jp (smtp02.silk.ntt-tx.co.jp [10.107.0.37]) by imss03.silk.ntt-tx.co.jp (unknown) with ESMTP id w185u33D011265 for unknown; Thu, 8 Feb 2018 14:56:03 +0900 Message-Id: <201802080556.w185u33D011265@imss03.silk.ntt-tx.co.jp> Received: from localhost by mgate02.silk.ntt-tx.co.jp (unknown) id w185u3ll019317 ; Thu, 8 Feb 2018 14:56:03 +0900 From: x-fn-spp@sl.ntt-tx.co.jp To: spp@dpdk.org Date: Thu, 8 Feb 2018 14:56:03 +0900 X-Mailer: git-send-email 1.9.1 In-Reply-To: <201802080551.w185pkLL010335@imss03.silk.ntt-tx.co.jp> References: <201802080551.w185pkLL010335@imss03.silk.ntt-tx.co.jp> X-TM-AS-MML: No Subject: [spp] [PATCH 3/9] spp_vf: change header file to doxygen format X-BeenThere: spp@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Soft Patch Panel List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 08 Feb 2018 05:56:05 -0000 From: Kentaro Watanabe Signed-off-by: Kentaro Watanabe Signed-off-by: Naoki Takada --- src/vf/classifier_mac.h | 49 ++++++- src/vf/command_conn.h | 26 ++-- src/vf/command_dec.h | 134 ++++++++++------- src/vf/command_proc.h | 13 +- src/vf/ringlatencystats.h | 39 ++++- src/vf/spp_forward.h | 55 ++++++- src/vf/spp_vf.h | 362 ++++++++++++++++++++++++++++++++++------------ src/vf/string_buffer.h | 14 +- 8 files changed, 510 insertions(+), 182 deletions(-) diff --git a/src/vf/classifier_mac.h b/src/vf/classifier_mac.h index b4e6715..b947bf7 100644 --- a/src/vf/classifier_mac.h +++ b/src/vf/classifier_mac.h @@ -1,12 +1,25 @@ #ifndef _CLASSIFIER_MAC_H_ #define _CLASSIFIER_MAC_H_ +/** + * @file + * SPP Classifier + * + * Classifier component provides packet forwarding function from + * one port to one port. Classifier has table of virtual MAC address. + * According to this table, classifier lookups L2 destination MAC address + * and determines which port to be transferred to incoming packets. + */ + /* forward declaration */ struct spp_component_info; struct spp_iterate_classifier_table_params; /** * classifier(mac address) initialize globals. + * + * @retval 0 succeeded. + * @retval -1 failed. */ int spp_classifier_mac_init(void); @@ -14,10 +27,11 @@ int spp_classifier_mac_init(void); * classifier(mac address) update component info. * * @param component_info - * point to struct spp_component_info. + * The pointer to struct spp_component_info.@n + * The data for updating the internal data of classifier. * - * @ret_val 0 succeeded. - * @ret_val -1 failed. + * @retval 0 succeeded. + * @retval -1 failed. */ int spp_classifier_mac_update(struct spp_component_info *component_info); @@ -25,15 +39,27 @@ int spp_classifier_mac_update(struct spp_component_info *component_info); * classifier(mac address) thread function. * * @param id - * unique component ID. + * The unique component ID. + * + * @retval 0 succeeded. + * @retval -1 failed. */ int spp_classifier_mac_do(int id); -/* - * classifier get component status +/** + * classifier get component status. + * + * + * @param lcore_id + * The logical core ID for classifier. + * @param id + * The unique component ID. + * @param params + * The pointer to struct spp_iterate_core_params.@n + * Detailed data of classifier status. * - * @ret_val 0 succeeded. - * @ret_val -1 failed. + * @retval 0 succeeded. + * @retval -1 failed. */ int spp_classifier_get_component_status(unsigned int lcore_id, int id, @@ -41,6 +67,13 @@ spp_classifier_get_component_status(unsigned int lcore_id, int id, /** * classifier(mac address) iterate classifier table. + * + * @param params + * Point to struct spp_iterate_classifier_table_params.@n + * Detailed data of classifier table. + * + * @retval 0 succeeded. + * @retval -1 failed. */ int spp_classifier_mac_iterate_table( struct spp_iterate_classifier_table_params *params); diff --git a/src/vf/command_conn.h b/src/vf/command_conn.h index 8f3b9cf..b52ab32 100644 --- a/src/vf/command_conn.h +++ b/src/vf/command_conn.h @@ -1,6 +1,13 @@ #ifndef _COMMAND_CONN_H_ #define _COMMAND_CONN_H_ +/** + * @file + * SPP Connection + * + * Command connection management. + */ + /** result code - temporary error. please retry */ #define SPP_CONNERR_TEMPORARY -1 /** result code - fatal error occurred. should terminate process. */ @@ -10,10 +17,9 @@ * initialize command connection. * * @param controller_ip - * controller listen ip address. - * + * The controller's ip address. * @param controller_port - * controller listen port number. + * The controller's port number. * * @retval 0 succeeded. * @retval -1 failed. @@ -26,7 +32,7 @@ int spp_command_conn_init(const char *controller_ip, int controller_port); * @note bocking. * * @param sock - * socket that connect to controller. + * Socket number for connecting to controller. * * @retval 0 succeeded. * @retval SPP_CONNERR_TEMPORARY temporary error. please retry. @@ -39,7 +45,9 @@ int spp_connect_to_controller(int *sock); * @note non-blocking. * * @param sock - * socket that read data. + * The socket number for the connection. + * @param msgbuf + * The pointer to command message buffer. * * @retval 0 < succeeded. number of bytes received. * @retval 0 no receive message. @@ -54,13 +62,11 @@ int spp_receive_message(int *sock, char **msgbuf); * @note non-blocking. * * @param sock - * socket that write data. - * + * The socket number to be sent. * @param message - * send data. - * + * The pointer to the message to be sent. * @param message_len - * send data length. + * The length of message. * * @retval 0 succeeded. * @retval SPP_CONNERR_TEMPORARY temporary error. please reconnect. diff --git a/src/vf/command_dec.h b/src/vf/command_dec.h index 77cae87..3eb4bc4 100644 --- a/src/vf/command_dec.h +++ b/src/vf/command_dec.h @@ -1,29 +1,36 @@ #ifndef _COMMAND_DEC_H_ #define _COMMAND_DEC_H_ -/* max number of command per request */ +/** + * @file + * SPP command decode + * + * Decode and validate the command message string. + */ + +/** max number of command per request */ #define SPP_CMD_MAX_COMMANDS 32 -/* maximum number of parameters per command */ +/** maximum number of parameters per command */ #define SPP_CMD_MAX_PARAMETERS 8 -/* command name string buffer size (include null char) */ +/** command name string buffer size (include null char) */ #define SPP_CMD_NAME_BUFSZ 32 -/* command value string buffer size (include null char) */ +/** command value string buffer size (include null char) */ #define SPP_CMD_VALUE_BUFSZ 128 -/* string that specify unused */ +/** string that specify unused */ #define SPP_CMD_UNUSE "unuse" -/* decode error code */ +/** decode error code */ enum spp_command_decode_error_code { /* not use 0, in general 0 is OK */ - SPP_CMD_DERR_BAD_FORMAT = 1, - SPP_CMD_DERR_UNKNOWN_COMMAND, - SPP_CMD_DERR_NO_PARAM, - SPP_CMD_DERR_BAD_TYPE, - SPP_CMD_DERR_BAD_VALUE, + SPP_CMD_DERR_BAD_FORMAT = 1, /**< Wrong format */ + SPP_CMD_DERR_UNKNOWN_COMMAND, /**< Unknown command */ + SPP_CMD_DERR_NO_PARAM, /**< No parameters */ + SPP_CMD_DERR_BAD_TYPE, /**< Wrong data type */ + SPP_CMD_DERR_BAD_VALUE, /**< Wrong value */ }; /** @@ -33,28 +40,28 @@ enum spp_command_decode_error_code { * defined in command_dec.c */ enum spp_command_type { - SPP_CMDTYPE_CLASSIFIER_TABLE, - SPP_CMDTYPE_FLUSH, - SPP_CMDTYPE_CLIENT_ID, - SPP_CMDTYPE_STATUS, - SPP_CMDTYPE_EXIT, - SPP_CMDTYPE_COMPONENT, - SPP_CMDTYPE_PORT, - SPP_CMDTYPE_CANCEL, + SPP_CMDTYPE_CLASSIFIER_TABLE, /**< classifier_table command */ + SPP_CMDTYPE_FLUSH, /**< flush command */ + SPP_CMDTYPE_CLIENT_ID, /**< get_client_id command */ + SPP_CMDTYPE_STATUS, /**< status command */ + SPP_CMDTYPE_EXIT, /**< exit command */ + SPP_CMDTYPE_COMPONENT, /**< component command */ + SPP_CMDTYPE_PORT, /**< port command */ + SPP_CMDTYPE_CANCEL, /**< cancel command */ }; -/* "classifier_table" command specific parameters */ +/** "classifier_table" command specific parameters */ struct spp_command_classifier_table { - /* Action identifier (add or del) */ + /** Action identifier (add or del) */ enum spp_command_action action; - /* Classify type (currently only for mac) */ + /** Classify type (currently only for mac) */ enum spp_classifier_type type; - /* Value to be classified */ + /** Value to be classified */ char value[SPP_CMD_VALUE_BUFSZ]; - /* Destination port type and number */ + /** Destination port type and number */ struct spp_port_index port; }; @@ -63,61 +70,84 @@ struct spp_command_flush { /* nothing specific */ }; -/* "component" command parameters */ +/** "component" command parameters */ struct spp_command_component { - enum spp_command_action action; /* Action identifier (start or stop) */ - char name[SPP_CMD_NAME_BUFSZ]; /* Component name */ - unsigned int core; /* Logical core number */ - enum spp_component_type type; /* Component type */ + /**< Action identifier (start or stop) */ + enum spp_command_action action; + + /**< Component name */ + char name[SPP_CMD_NAME_BUFSZ]; + + /**< Logical core number */ + unsigned int core; + + /**< Component type */ + enum spp_component_type type; }; -/* "port" command parameters */ +/** "port" command parameters */ struct spp_command_port { - enum spp_command_action action; /* Action identifier (add or del) */ - struct spp_port_index port; /* Port type and number */ - enum spp_port_rxtx rxtx; /* rx/tx identifier */ - char name[SPP_CMD_NAME_BUFSZ]; /* Attached component name */ + enum spp_command_action action; /**< Action identifier (add or del) */ + struct spp_port_index port; /**< Port type and number */ + enum spp_port_rxtx rxtx; /**< rx/tx identifier */ + char name[SPP_CMD_NAME_BUFSZ]; /**< Attached component name */ }; -/* command parameters */ +/** command parameters */ struct spp_command { - enum spp_command_type type; /* Command type */ + enum spp_command_type type; /**< Command type */ union { - /* Structured data for classifier_table command */ + /** Structured data for classifier_table command */ struct spp_command_classifier_table classifier_table; - /* Structured data for flush command */ + /** Structured data for flush command */ struct spp_command_flush flush; - /* Structured data for component command */ + /** Structured data for component command */ struct spp_command_component component; - /* Structured data for port command */ + /** Structured data for port command */ struct spp_command_port port; } spec; }; -/* request parameters */ +/** request parameters */ struct spp_command_request { - int num_command; /* Number of accepted commands */ - int num_valid_command; /* Number of executed commands */ + int num_command; /**< Number of accepted commands */ + int num_valid_command; /**< Number of executed commands */ struct spp_command commands[SPP_CMD_MAX_COMMANDS]; - /* Information of executed commands */ + /**< Information of executed commands */ - int is_requested_client_id; /* Id for get_client_id command */ - int is_requested_status; /* Id for status command */ - int is_requested_exit; /* Id for exit command */ + int is_requested_client_id; /**< Id for get_client_id command */ + int is_requested_status; /**< Id for status command */ + int is_requested_exit; /**< Id for exit command */ }; -/* decode error information */ +/** decode error information */ struct spp_command_decode_error { - int code; /* Error code */ - char value_name[SPP_CMD_NAME_BUFSZ]; /* Error value name */ - char value[SPP_CMD_VALUE_BUFSZ]; /* Error value */ + int code; /**< Error code */ + char value_name[SPP_CMD_NAME_BUFSZ]; /**< Error value name */ + char value[SPP_CMD_VALUE_BUFSZ]; /**< Error value */ }; -/* decode request from no-null-terminated string */ +/** + * decode request from no-null-terminated string + * + * @param request + * The pointer to struct spp_command_request.@n + * The result value of decoding the command message. + * @param request_str + * The pointer to requested command message. + * @param request_str_len + * The length of requested command message. + * @param error + * The pointer to struct spp_command_decode_error.@n + * Detailed error information will be stored. + * + * @retval 0 succeeded. + * @retval !0 failed. + */ int spp_command_decode_request(struct spp_command_request *request, const char *request_str, size_t request_str_len, struct spp_command_decode_error *error); diff --git a/src/vf/command_proc.h b/src/vf/command_proc.h index 6b88da7..04296de 100644 --- a/src/vf/command_proc.h +++ b/src/vf/command_proc.h @@ -2,13 +2,20 @@ #define _COMMAND_PROC_H_ /** + * @file + * SPP Command processing + * + * Receive and process the command message, then send back the + * result JSON formatted data. + */ + +/** * initialize command processor. * * @param controller_ip - * controller listen IP address. - * + * The controller's ip address. * @param controller_port - * controller listen port number. + * The controller's port number. * * @retval 0 succeeded. * @retval -1 failed. diff --git a/src/vf/ringlatencystats.h b/src/vf/ringlatencystats.h index 2e64d63..5bc230d 100644 --- a/src/vf/ringlatencystats.h +++ b/src/vf/ringlatencystats.h @@ -1,6 +1,13 @@ #ifndef _RINGLATENCYSTATS_H_ #define _RINGLATENCYSTATS_H_ +/** + * @file + * SPP RING latency statistics + * + * Measure the latency through ring-PMD. + */ + #include /** number of slots to save latency. 0ns~99ns and 100ns over */ @@ -8,7 +15,7 @@ /** ring latency statistics */ struct spp_ringlatencystats_ring_latency_stats { - /**< slots to save latency */ + /** slots to save latency */ uint64_t slot[SPP_RINGLATENCYSTATS_STATS_SLOT_COUNT]; }; @@ -17,6 +24,11 @@ struct spp_ringlatencystats_ring_latency_stats { /** * initialize ring latency statistics. * + * @param samp_intvl + * The interval timer(ns) to refer the counter. + * @param stats_count + * The number of ring to be measured. + * * @retval 0: succeeded. * @retval -1: failed. */ @@ -30,7 +42,15 @@ void spp_ringlatencystats_uninit(void); /** * add time-stamp to mbuf's member. * - * call at enqueue. + * @note call at enqueue. + * + * @param ring_id + * The ring id. + * @param pkts + * The address of an array of nb_pkts pointers to rte_mbuf structures + * which contain the packets to be measured. + * @param nb_pkts + * The maximum number of packets to be measured. */ void spp_ringlatencystats_add_time_stamp(int ring_id, struct rte_mbuf **pkts, uint16_t nb_pkts); @@ -38,7 +58,15 @@ void spp_ringlatencystats_add_time_stamp(int ring_id, /** * calculate latency. * - * call at dequeue. + * @note call at dequeue. + * + * @param ring_id + * The ring id. + * @param pkts + * The address of an array of nb_pkts pointers to rte_mbuf structures + * which contain the packets to be measured. + * @param nb_pkts + * The maximum number of packets to be measured. */ void spp_ringlatencystats_calculate_latency(int ring_id, struct rte_mbuf **pkts, uint16_t nb_pkts); @@ -52,6 +80,11 @@ int spp_ringlatencystats_get_count(void); /** *get specific ring latency statistics. + * + * @param ring_id + * The ring id. + * @param stats + * The statistics values. */ void spp_ringlatencystats_get_stats(int ring_id, struct spp_ringlatencystats_ring_latency_stats *stats); diff --git a/src/vf/spp_forward.h b/src/vf/spp_forward.h index 5e5cf0f..b2965a6 100644 --- a/src/vf/spp_forward.h +++ b/src/vf/spp_forward.h @@ -1,21 +1,62 @@ #ifndef __SPP_FORWARD_H__ #define __SPP_FORWARD_H__ -/* Clear info */ -void spp_forward_init(void); +/** + * @file + * SPP Forwarder and Merger + * + * Forwarder + * This component provides function for packet processing from one port + * to one port. Incoming packets from port are to be transferred to + * specific one port. The direction of this transferring is specified + * by port command. + * Merger + * This component provides packet forwarding function from multiple + * ports to one port. Incoming packets from multiple ports are to be + * transferred to one specific port. The flow of this merging process + * is specified by port command. + */ -/* Clear info for one element. */ -void spp_forward_init_info(int id); +/** Clear info */ +void spp_forward_init(void); -/* Update forward info */ +/** + * Update forward info + * + * @param component + * The pointer to struct spp_component_info.@n + * The data for updating the internal data of forwarder and merger. + * + * @retval 0 succeeded. + * @retval -1 failed. + */ int spp_forward_update(struct spp_component_info *component); -/* +/** * Merge/Forward + * + * @param id + * The unique component ID. + * + * @retval 0 succeeded. + * @retval -1 failed. */ int spp_forward(int id); -/* Merge/Forward get component status */ +/** + * Merge/Forward get component status + * + * @param lcore_id + * The logical core ID for forwarder and merger. + * @param id + * The unique component ID. + * @param params + * The pointer to struct spp_iterate_core_params.@n + * Detailed data of forwarder/merger status. + * + * @retval 0 succeeded. + * @retval -1 failed. + */ int spp_forward_get_component_status( unsigned int lcore_id, int id, struct spp_iterate_core_params *params); diff --git a/src/vf/spp_vf.h b/src/vf/spp_vf.h index 07f2e2a..70e105b 100644 --- a/src/vf/spp_vf.h +++ b/src/vf/spp_vf.h @@ -1,128 +1,164 @@ #ifndef __SPP_VF_H__ #define __SPP_VF_H__ +/** + * @file + * SPP_VF main + * + * Main function of spp_vf. + * This provides the function for initializing and starting the threads. + */ + #include "common.h" +/** Identifier string for each component (status command) @{*/ #define SPP_TYPE_CLASSIFIER_MAC_STR "classifier_mac" #define SPP_TYPE_MERGE_STR "merge" #define SPP_TYPE_FORWARD_STR "forward" #define SPP_TYPE_UNUSE_STR "unuse" +/**@}*/ +/** Identifier string for each interface @{*/ #define SPP_IFTYPE_NIC_STR "phy" #define SPP_IFTYPE_VHOST_STR "vhost" #define SPP_IFTYPE_RING_STR "ring" +/**@}*/ +/** The max number of client ID */ #define SPP_CLIENT_MAX 128 + +/** The max number of buffer for management */ #define SPP_INFO_AREA_MAX 2 + +/** The length of shortest character string */ #define SPP_MIN_STR_LEN 32 + +/** The length of NAME string */ #define SPP_NAME_STR_LEN 128 +/** Update wait timer (micro sec) */ #define SPP_CHANGE_UPDATE_INTERVAL 10 +/** Character sting for default port of classifier */ #define SPP_DEFAULT_CLASSIFIED_SPEC_STR "default" + +/** Character sting for default MAC address of classifier */ #define SPP_DEFAULT_CLASSIFIED_DMY_ADDR_STR "00:00:00:00:00:01" + +/** Value for default MAC address of classifier */ #define SPP_DEFAULT_CLASSIFIED_DMY_ADDR 0x010000000000 -/* +/** * State on component */ enum spp_core_status { - SPP_CORE_UNUSE, - SPP_CORE_STOP, - SPP_CORE_IDLE, - SPP_CORE_FORWARD, - SPP_CORE_STOP_REQUEST, - SPP_CORE_IDLE_REQUEST + SPP_CORE_UNUSE, /**< Not used */ + SPP_CORE_STOP, /**< Stopped */ + SPP_CORE_IDLE, /**< Idling */ + SPP_CORE_FORWARD, /**< Forwarding */ + SPP_CORE_STOP_REQUEST, /**< Request stopping */ + SPP_CORE_IDLE_REQUEST /**< Request idling */ }; -/* +/** * Process type for each component */ enum spp_component_type { - SPP_COMPONENT_UNUSE, - SPP_COMPONENT_CLASSIFIER_MAC, - SPP_COMPONENT_MERGE, - SPP_COMPONENT_FORWARD, + SPP_COMPONENT_UNUSE, /**< Not used */ + SPP_COMPONENT_CLASSIFIER_MAC, /**< Classifier_mac */ + SPP_COMPONENT_MERGE, /**< Merger */ + SPP_COMPONENT_FORWARD, /**< Forwarder */ }; -/* +/** * Classifier Type */ enum spp_classifier_type { - SPP_CLASSIFIER_TYPE_NONE, - SPP_CLASSIFIER_TYPE_MAC + SPP_CLASSIFIER_TYPE_NONE, /**< Type none */ + SPP_CLASSIFIER_TYPE_MAC /**< MAC address */ }; -/* +/** * API Return value */ enum spp_return_value { - SPP_RET_OK = 0, - SPP_RET_NG = -1, + SPP_RET_OK = 0, /**< succeeded */ + SPP_RET_NG = -1, /**< failed */ }; -/* Port type (rx or tx) */ +/** Port type (rx or tx) */ enum spp_port_rxtx { - SPP_PORT_RXTX_NONE, - SPP_PORT_RXTX_RX, - SPP_PORT_RXTX_TX, - SPP_PORT_RXTX_ALL, + SPP_PORT_RXTX_NONE, /**< none */ + SPP_PORT_RXTX_RX, /**< rx port */ + SPP_PORT_RXTX_TX, /**< tx port */ + SPP_PORT_RXTX_ALL, /**< rx/tx port */ }; -/* command setting type */ +/** command setting type */ enum spp_command_action { - SPP_CMD_ACTION_NONE, - SPP_CMD_ACTION_START, - SPP_CMD_ACTION_STOP, - SPP_CMD_ACTION_ADD, - SPP_CMD_ACTION_DEL, + SPP_CMD_ACTION_NONE, /**< none */ + SPP_CMD_ACTION_START, /**< start */ + SPP_CMD_ACTION_STOP, /**< stop */ + SPP_CMD_ACTION_ADD, /**< add */ + SPP_CMD_ACTION_DEL, /**< delete */ }; -/* +/** * Interface information structure */ struct spp_port_index { - enum port_type iface_type; /* Interface type (phy/vhost/ring) */ - int iface_no; /* Interface number */ + enum port_type iface_type; /**< Interface type (phy/vhost/ring) */ + int iface_no; /**< Interface number */ }; -/* +/** * Port info */ struct spp_port_info { - enum port_type iface_type; /* Interface type (phy/vhost/ring) */ - int iface_no; /* Interface number */ - int dpdk_port; /* DPDK port number */ - uint64_t mac_addr; /* Mac address for classifying */ - char mac_addr_str[SPP_MIN_STR_LEN]; /* Mac address */ + enum port_type iface_type; /**< Interface type (phy/vhost/ring) */ + int iface_no; /**< Interface number */ + int dpdk_port; /**< DPDK port number */ + uint64_t mac_addr; /**< Mac address for classifying */ + char mac_addr_str[SPP_MIN_STR_LEN]; /**< Mac address */ }; -/* +/** * Component info */ struct spp_component_info { - char name[SPP_NAME_STR_LEN]; /* Component name */ - enum spp_component_type type; /* Component type */ - unsigned int lcore_id; /* Logical core ID for component */ - int component_id; /* Component ID */ - int num_rx_port; /* The number of rx ports */ - int num_tx_port; /* The number of tx ports */ + char name[SPP_NAME_STR_LEN]; /**< Component name */ + enum spp_component_type type; /**< Component type */ + unsigned int lcore_id; /**< Logical core ID for component */ + int component_id; /**< Component ID */ + int num_rx_port; /**< The number of rx ports */ + int num_tx_port; /**< The number of tx ports */ struct spp_port_info *rx_ports[RTE_MAX_ETHPORTS]; - /* Array of pointers to rx ports */ + /**< Array of pointers to rx ports */ struct spp_port_info *tx_ports[RTE_MAX_ETHPORTS]; - /* Array of pointers to tx ports */ + /**< Array of pointers to tx ports */ }; -/* +/** * Get client ID - * RETURN : CLIENT ID(0~127) + * + * @return Client ID(0~127) */ int spp_get_client_id(void); -/* +/** * Update Classifier_table - * OK : SPP_RET_OK(0) - * NG : SPP_RET_NG(-1) + * + * @param action + * Action identifier (add or del) + * @param type + * Classify type (currently only for mac) + * @param data + * Value to be classified + * @param port + * Destination port type and number + * + * @retval SPP_RET_OK succeeded. + * @retval SPP_RET_NG failed. */ int spp_update_classifier_table( enum spp_command_action action, @@ -130,20 +166,40 @@ int spp_update_classifier_table( const char *data, const struct spp_port_index *port); -/* +/** * Update component - * OK : SPP_RET_OK(0) - * NG : SPP_RET_NG(-1) + * + * @param action + * Action identifier (start or stop) + * @param name + * Component name + * @param lcore_id + * Logical core number + * @param type + * Component type + * + * @retval SPP_RET_OK succeeded. + * @retval SPP_RET_NG failed. */ int spp_update_component( enum spp_command_action action, const char *name, unsigned int lcore_id, enum spp_component_type type); -/* +/** * Update port - * OK : SPP_RET_OK(0) - * NG : SPP_RET_NG(-1) + * + * @param action + * Action identifier (add or del) + * @param port + * Port type and number + * @param rxtx + * rx/tx identifier + * @param name + * Attached component name + * + * @retval SPP_RET_OK succeeded. + * @retval SPP_RET_NG failed. */ int spp_update_port( enum spp_command_action action, @@ -151,19 +207,20 @@ int spp_update_port( enum spp_port_rxtx rxtx, const char *name); -/* +/** * Flush SPP component - * OK : SPP_RET_OK(0) - * NG : SPP_RET_NG(-1) + * + * @retval SPP_RET_OK succeeded. + * @retval SPP_RET_NG failed. */ int spp_flush(void); -/* +/** * Cancel data that is not flushing */ void spp_cancel(void); -/* definition of iterated core element procedure function */ +/** definition of iterated core element procedure function */ struct spp_iterate_core_params; typedef int (*spp_iterate_core_element_proc)( struct spp_iterate_core_params *params, @@ -175,16 +232,28 @@ typedef int (*spp_iterate_core_element_proc)( const int num_tx, const struct spp_port_index *tx_ports); -/* iterate core information parameters */ +/** iterate core information parameters */ struct spp_iterate_core_params { + /** Output buffer */ char *output; + + /** The function for creating core information */ spp_iterate_core_element_proc element_proc; }; -/* Iterate core information */ +/** + * Iterate core information + * + * @param params + * The pointer to struct spp_iterate_core_params.@n + * The value for generating core information (status command). + * + * @retval SPP_RET_OK succeeded. + * @retval SPP_RET_NG failed. + */ int spp_iterate_core_info(struct spp_iterate_core_params *params); -/* definition of iterated classifier element procedure function */ +/** definition of iterated classifier element procedure function */ struct spp_iterate_classifier_table_params; typedef int (*spp_iterate_classifier_element_proc)( struct spp_iterate_classifier_table_params *params, @@ -192,105 +261,206 @@ typedef int (*spp_iterate_classifier_element_proc)( const char *data, const struct spp_port_index *port); -/* iterate classifier table parameters */ +/** iterate classifier table parameters */ struct spp_iterate_classifier_table_params { void *output; spp_iterate_classifier_element_proc element_proc; }; -/* +/** * Iterate Classifier_table + * + * @param params + * The pointer to struct spp_iterate_classifier_table_params.@n + * The value for generating classifier table. + * + * @retval SPP_RET_OK succeeded. + * @retval SPP_RET_NG failed. */ int spp_iterate_classifier_table( struct spp_iterate_classifier_table_params *params); -/* Get core status */ +/** + * Get core status + * + * @param lcore_id + * Logical core ID. + * + * @return + * Status of specified logical core. + */ enum spp_core_status spp_get_core_status(unsigned int lcore_id); -/* Get component type of target core */ +/** + * Get component type of target core + * + * @param lcore_id + * Logical core ID. + * + * @return + * Type of component executed on specified logical core + */ enum spp_component_type spp_get_component_type(unsigned int lcore_id); -/* Get component type being updated on target core */ +/** + * Get component type being updated on target core + * + * @param lcore_id + * Logical core ID. + * + * @return + * Type of component that will be executed on + * specified logical core after update. + */ enum spp_component_type spp_get_component_type_update(unsigned int lcore_id); -/* +/** * Get core ID of target component - * RETURN : core ID + * + * @param component_id + * unique component ID. + * + * @return + * Logical core id of specified component. */ unsigned int spp_get_component_core(int component_id); -/* +/** * Check core index change - * RETURN : True if index has changed. + * + * @param lcore_id + * Logical core ID. + * + * @return + * True if index has changed. */ int spp_check_core_index(unsigned int lcore_id); -/* +/** * Get name matching component ID - * OK : component ID - * NG : SPP_RET_NG + * + * @param name + * Component name. + * + * @retval 0~127 Component ID. + * @retval SPP_RET_NG failed. */ int spp_get_component_id(const char *name); /** * Check mac address used on the port for registering or removing - * RETURN : True if target MAC address matches MAC address of port. + * + * @param mac_addr + * Mac address to be validated. + * @param iface_type + * Interface to be validated. + * @param iface_no + * Interface number to be validated. + * + * @return + * True if target MAC address matches MAC address of port. */ int spp_check_mac_used_port( uint64_t mac_addr, enum port_type iface_type, int iface_no); -/* +/** * Check if port has been added. - * RETURN : True if port has been added. + * + * @param iface_type + * Interface to be validated. + * @param iface_no + * Interface number to be validated. + * + * @return + * True if port has been added. */ int spp_check_added_port(enum port_type iface_type, int iface_no); -/* +/** * Check if port has been flushed. - * RETURN : True if port has been flushed. + * + * @param iface_type + * Interface to be validated. + * @param iface_no + * Interface number to be validated. + * + * @return + * True if port has been flushed. */ int spp_check_flush_port(enum port_type iface_type, int iface_no); -/* +/** * Check if component is using port. - * OK : match component ID - * NG : SPP_RET_NG + * + * @param iface_type + * Interface type to be validated. + * @param iface_no + * Interface number to be validated. + * @param rxtx + * tx/rx type to be validated. + * + * @retval 0~127 match component ID + * @retval SPP_RET_NG failed. */ int spp_check_used_port( enum port_type iface_type, int iface_no, enum spp_port_rxtx rxtx); -/* +/** * Change mac address string to int64 - * OK : int64 that store mac address - * NG : -1 + * + * @param mac + * Character string of MAC address to be converted. + * + * @retval 0< int64 that store mac address + * @retval -1 */ int64_t spp_change_mac_str_to_int64(const char *mac); -/* +/** * Extract if-type/if-number from port string * - * OK : 0 - * NG : -1 + * @param port + * Character string expressing the port, e.g. "phy:0","ring:1" + * @param iface_type + * Interface type obtained from port. + * @param iface_no + * Interface number obtained from port. + * + * @retval 0 succeeded. + * @retval -1 failed. */ int spp_get_iface_index( const char *port, enum port_type *iface_type, int *iface_no); -/* +/** * Format port string form if-type/if-number * - * OK : 0 - * NG : -1 + * @param port + * Character string expressing the port, e.g. "phy:0","ring:1" + * @param iface_type + * Interface type. + * @param iface_no + * Interface number. + * + * @retval 0 succeeded. + * @retval -1 failed. */ int spp_format_port_string(char *port, enum port_type iface_type, int iface_no); -/* +/** * Change component type from string to type value. + * + * @param type_str + * Name string for each component + * + * @return + * Component type corresponding to type_str. */ enum spp_component_type spp_change_component_type(const char *type_str); diff --git a/src/vf/string_buffer.h b/src/vf/string_buffer.h index 60645e9..947748e 100644 --- a/src/vf/string_buffer.h +++ b/src/vf/string_buffer.h @@ -2,6 +2,14 @@ #define _STRING_BUFFER_H_ /** + * @file + * SPP String buffer management + * + * Management features of string buffer which is used for communicating + * between spp_vf and controller. + */ + +/** * allocate string buffer from heap memory. * * @attention allocated memory must free by spp_strbuf_free function. @@ -28,10 +36,8 @@ void spp_strbuf_free(char *strbuf); * @param strbuf * destination string buffer. * spp_strbuf_allocate/spp_strbuf_append return value. - * * @param append * string to append. normal c-string. - * * @param append_len * length of append string. * @@ -46,9 +52,11 @@ char *spp_strbuf_append(char *strbuf, const char *append, size_t append_len); * @param strbuf * target string buffer. * spp_strbuf_allocate/spp_strbuf_append return value. - * * @param remove_len * length of remove. + * + * @return + * The pointer to removed string. */ char *spp_strbuf_remove_front(char *strbuf, size_t remove_len); -- 1.9.1