From patchwork Wed Mar 26 13:47:57 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Petri Savolainen X-Patchwork-Id: 27136 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-pb0-f72.google.com (mail-pb0-f72.google.com [209.85.160.72]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id BB40E20062 for ; Wed, 26 Mar 2014 13:45:52 +0000 (UTC) Received: by mail-pb0-f72.google.com with SMTP id jt11sf4681185pbb.11 for ; Wed, 26 Mar 2014 06:45:52 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:from:to:cc:subject:date:message-id :x-original-sender:x-original-authentication-results:precedence :mailing-list:list-id:list-post:list-help:list-archive :list-unsubscribe:content-type; bh=zzHtYUQ4iioaTRqii8rvqMIDFZSMWIl+qCy5U+/j1DQ=; b=ksGKxIZrZYWgYYaoF71NrIavhjQuWmGV3LR2JATghcdlQpQ46KSr5lvUEDRwwET2qp 9BemQSNATtAH/hMB6N+bJj5ldAPoU97taAjOok3OKt+H2RRpkJ/shhN3D5PhybM2vDys GdahtrueXAPBlJYI0jn8ccgoX5BxEBbA1NM5AdJVDV5UiRSV+8nDurmpQu+gJLYySzls qD8f4DiGtIfLg9dlv7FVo8omdKb9cdeviqr0Tox2kR+MYhIjzxdzXrreWKpVVLOb5CCW oWiKovDAlHgRgIf1fi4pBaDD5leFSinIWcNyd20mMw5EG4G6aqIcFe5izDKvqnRJZwmx 5BQA== X-Gm-Message-State: ALoCoQmPBi1yzKLSKDw7IwTRH4dOdZ7va5D6BUDlWmByQ6PWD/jK3tzRl/We2jCBigOSQoEY1kTT X-Received: by 10.66.137.105 with SMTP id qh9mr1786890pab.30.1395841551986; Wed, 26 Mar 2014 06:45:51 -0700 (PDT) MIME-Version: 1.0 X-BeenThere: lng-odp@linaro.org Received: by 10.140.97.72 with SMTP id l66ls624685qge.16.gmail; Wed, 26 Mar 2014 06:45:51 -0700 (PDT) X-Received: by 10.224.25.196 with SMTP id a4mr70078837qac.3.1395841551687; Wed, 26 Mar 2014 06:45:51 -0700 (PDT) Received: from mail-qc0-f180.google.com (mail-qc0-f180.google.com [209.85.216.180]) by mx.google.com with ESMTPS id 5si8971766qch.25.2014.03.26.06.45.51 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 26 Mar 2014 06:45:51 -0700 (PDT) Received-SPF: neutral (google.com: 209.85.216.180 is neither permitted nor denied by best guess record for domain of petri.savolainen@linaro.org) client-ip=209.85.216.180; Received: by mail-qc0-f180.google.com with SMTP id w7so2530688qcr.39 for ; Wed, 26 Mar 2014 06:45:51 -0700 (PDT) X-Received: by 10.140.37.194 with SMTP id r60mr36930184qgr.61.1395841551471; Wed, 26 Mar 2014 06:45:51 -0700 (PDT) Received: from localhost.localdomain (ec2-23-23-178-99.compute-1.amazonaws.com. [23.23.178.99]) by mx.google.com with ESMTPSA id f2sm38730742qaa.28.2014.03.26.06.45.48 for (version=TLSv1.1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 26 Mar 2014 06:45:50 -0700 (PDT) From: Petri Savolainen To: lng-odp@linaro.org Cc: Petri Savolainen Subject: [lng-odp] [PATCH] Clean Doxygen warnings Date: Wed, 26 Mar 2014 15:47:57 +0200 Message-Id: <1395841677-8606-1-git-send-email-petri.savolainen@linaro.org> X-Mailer: git-send-email 1.8.5.3 X-Original-Sender: petri.savolainen@linaro.org X-Original-Authentication-Results: mx.google.com; spf=neutral (google.com: 209.85.216.180 is neither permitted nor denied by best guess record for domain of petri.savolainen@linaro.org) smtp.mail=petri.savolainen@linaro.org Precedence: list Mailing-list: list lng-odp@linaro.org; contact lng-odp+owners@linaro.org List-ID: X-Google-Group-Id: 474323889996 List-Post: , List-Help: , List-Archive: List-Unsubscribe: , Cleaned warnings on include, include/helper and test/example. Used @internal and @private to mark documentation that should not go into ODP API docs. Doxyfile.in needs INTERNAL_DOCS = YES to suppress warnings (of @internal), but it should be set "NO" for "official" documentation generation. Signed-off-by: Petri Savolainen --- include/helper/odp_eth.h | 31 +++++---- include/helper/odp_ip.h | 66 ++++++++++++++----- include/helper/odp_linux.h | 6 +- include/helper/odp_packet_helper.h | 4 +- include/helper/odp_ring.h | 14 +++-- include/helper/odp_udp.h | 8 ++- include/odp_align.h | 68 ++++++++++++++++++-- include/odp_barrier.h | 4 +- include/odp_buffer.h | 2 +- include/odp_buffer_pool.h | 5 +- include/odp_byteorder.h | 8 +++ include/odp_compiler.h | 4 +- include/odp_coremask.h | 4 +- include/odp_packet.h | 3 + include/odp_packet_io.h | 8 ++- include/odp_queue.h | 34 +++++++--- include/odp_shared_memory.h | 2 +- include/odp_spinlock.h | 2 +- include/odp_sync.h | 6 ++ include/odp_ticketlock.h | 4 +- include/odp_timer.h | 2 + include/odp_version.h | 5 +- platform/linux-generic/Doxyfile.in | 2 + test/example/odp_example.c | 126 +++++++++++++++++++++++++++---------- 24 files changed, 318 insertions(+), 100 deletions(-) diff --git a/include/helper/odp_eth.h b/include/helper/odp_eth.h index d1cb33b..401b915 100644 --- a/include/helper/odp_eth.h +++ b/include/helper/odp_eth.h @@ -23,42 +23,47 @@ extern "C" { #include #include -#define ODP_ETHADDR_LEN 6 -#define ODP_ETHHDR_LEN 14 -#define ODP_VLANHDR_LEN 4 -#define ODP_ETH_LEN_MIN 60 /* exclude 4B CRC/FCS */ -#define ODP_ETH_LEN_MIN_CRC 64 /* include 4B CRC/FCS */ -#define ODP_ETH_LEN_MAX 1514 /* exclude 4B CRC/FCS */ -#define ODP_ETH_LEN_MAX_CRC 1518 /* include 4B CRC/FCS */ +#define ODP_ETHADDR_LEN 6 /**< Ethernet address length */ +#define ODP_ETHHDR_LEN 14 /**< Ethernet header length */ +#define ODP_VLANHDR_LEN 4 /**< VLAN header length */ +#define ODP_ETH_LEN_MIN 60 /**< Min frame length (excl. CRC 4 bytes) */ +#define ODP_ETH_LEN_MIN_CRC 64 /**< Min frame length (incl. CRC 4 bytes) */ +#define ODP_ETH_LEN_MAX 1514 /**< Max frame length (excl. CRC 4 bytes) */ +#define ODP_ETH_LEN_MAX_CRC 1518 /**< Max frame length (incl. CRC 4 bytes) */ /** * Ethernet MAC address */ typedef struct ODP_PACKED { - uint8_t addr[ODP_ETHADDR_LEN]; + uint8_t addr[ODP_ETHADDR_LEN]; /**< @private Address */ } odp_ethaddr_t; +/** @internal Compile time assert */ ODP_ASSERT(sizeof(odp_ethaddr_t) == ODP_ETHADDR_LEN, ODP_ETHADDR_T__SIZE_ERROR); /** * Ethernet header */ typedef struct ODP_PACKED { - odp_ethaddr_t dst; - odp_ethaddr_t src; - uint16be_t type; + odp_ethaddr_t dst; /**< Destination address */ + odp_ethaddr_t src; /**< Source address */ + uint16be_t type; /**< Type */ } odp_ethhdr_t; +/** @internal Compile time assert */ ODP_ASSERT(sizeof(odp_ethhdr_t) == ODP_ETHHDR_LEN, ODP_ETHHDR_T__SIZE_ERROR); /** * VLAN header + * + * @todo Check usage of tpid vs ethertype. Check outer VLAN TPID. */ typedef struct ODP_PACKED { - uint16be_t tpid; - uint16be_t tci; + uint16be_t tpid; /**< Tag protocol ID (located after ethhdr.src) */ + uint16be_t tci; /**< Priority / CFI / VLAN ID */ } odp_vlanhdr_t; +/** @internal Compile time assert */ ODP_ASSERT(sizeof(odp_vlanhdr_t) == ODP_VLANHDR_LEN, ODP_VLANHDR_T__SIZE_ERROR); diff --git a/include/helper/odp_ip.h b/include/helper/odp_ip.h index af6d23b..9a1d140 100644 --- a/include/helper/odp_ip.h +++ b/include/helper/odp_ip.h @@ -29,29 +29,48 @@ extern "C" { #define ODP_IPV4HDR_LEN 20 /**< Min length of IP header (no options) */ #define ODP_IPV4HDR_IHL_MIN 5 /**< Minimum IHL value*/ +/** @internal Returns IPv4 version */ #define ODP_IPV4HDR_VER(ver_ihl) (((ver_ihl) & 0xf0) >> 4) + +/** @internal Returns IPv4 header length */ #define ODP_IPV4HDR_IHL(ver_ihl) ((ver_ihl) & 0x0f) + +/** @internal Returns IPv4 Don't fragment */ #define ODP_IPV4HDR_FLAGS_DONT_FRAG(frag_offset) ((frag_offset) & 0x4000) + +/** @internal Returns IPv4 more fragments */ #define ODP_IPV4HDR_FLAGS_MORE_FRAGS(frag_offset) ((frag_offset) & 0x2000) + +/** @internal Returns IPv4 fragment offset */ #define ODP_IPV4HDR_FRAG_OFFSET(frag_offset) ((frag_offset) & 0x1fff) +/** @internal Returns true if IPv4 packet is a fragment */ #define ODP_IPV4HDR_IS_FRAGMENT(frag_offset) ((frag_offset) & 0x3fff) +/** IPv4 header */ typedef struct ODP_PACKED { - uint8_t ver_ihl; - uint8_t tos; - uint16be_t tot_len; - uint16be_t id; - uint16be_t frag_offset; - uint8_t ttl; - uint8_t proto; - uint16be_t chksum; - uint32be_t src_addr; - uint32be_t dst_addr; + uint8_t ver_ihl; /**< Version / Header length */ + uint8_t tos; /**< Type of service */ + uint16be_t tot_len; /**< Total length */ + uint16be_t id; /**< ID */ + uint16be_t frag_offset; /**< Fragmentation offset */ + uint8_t ttl; /**< Time to live */ + uint8_t proto; /**< Protocol */ + uint16be_t chksum; /**< Checksum */ + uint32be_t src_addr; /**< Source address */ + uint32be_t dst_addr; /**< Destination address */ } odp_ipv4hdr_t; +/** @internal Compile time assert */ ODP_ASSERT(sizeof(odp_ipv4hdr_t) == ODP_IPV4HDR_LEN, ODP_IPV4HDR_T__SIZE_ERROR); +/** + * Check if IPv4 checksum is valid + * + * @param pkt ODP packet + * + * @return 1 if checksum is valid, otherwise 0 + */ static inline int odp_ipv4_csum_valid(odp_packet_t pkt) { uint16be_t res = 0; @@ -72,7 +91,13 @@ static inline int odp_ipv4_csum_valid(odp_packet_t pkt) return (res == chksum) ? 1 : 0; } - +/** + * Calculate and fill in IPv4 checksum + * + * @param pkt ODP packet + * + * @return IPv4 checksum, or 0 on failure + */ static inline uint16be_t odp_ipv4_csum_update(odp_packet_t pkt) { uint16be_t res = 0; @@ -90,18 +115,25 @@ static inline uint16be_t odp_ipv4_csum_update(odp_packet_t pkt) return res; } +/** IPv6 version */ #define ODP_IPV6 6 + +/** IPv6 header length */ #define ODP_IPV6HDR_LEN 40 +/** + * IPv6 header + */ typedef struct ODP_PACKED { - uint32be_t ver_tc_flow; - uint16be_t payload_len; - uint8_t next_hdr; - uint8_t hop_limit; - uint8_t src_addr[16]; - uint8_t dst_addr[16]; + uint32be_t ver_tc_flow; /**< Version / Traffic class / Flow label */ + uint16be_t payload_len; /**< Payload length */ + uint8_t next_hdr; /**< Next header */ + uint8_t hop_limit; /**< Hop limit */ + uint8_t src_addr[16]; /**< Source address */ + uint8_t dst_addr[16]; /**< Destination address */ } odp_ipv6hdr_t; +/** @internal Compile time assert */ ODP_ASSERT(sizeof(odp_ipv6hdr_t) == ODP_IPV6HDR_LEN, ODP_IPV6HDR_T__SIZE_ERROR); /* IP protocol values (IPv4:'proto' or IPv6:'next_hdr') */ diff --git a/include/helper/odp_linux.h b/include/helper/odp_linux.h index 38a1f51..3e91ce0 100644 --- a/include/helper/odp_linux.h +++ b/include/helper/odp_linux.h @@ -24,10 +24,10 @@ extern "C" { #include - +/** Pthread status data */ typedef struct { - pthread_t thread; - pthread_attr_t attr; + pthread_t thread; /**< @private Pthread */ + pthread_attr_t attr; /**< @private Pthread attributes */ } odp_linux_pthread_t; diff --git a/include/helper/odp_packet_helper.h b/include/helper/odp_packet_helper.h index ce3ce4d..eed866e 100644 --- a/include/helper/odp_packet_helper.h +++ b/include/helper/odp_packet_helper.h @@ -39,7 +39,7 @@ static inline int odp_packet_is_valid(odp_packet_t pkt) /** * Helper: Allocate and initialize a packet buffer from a packet pool * - * @param pool Pool handle + * @param pool_id Pool handle * * @note The pool must have been created with 'buf_type=ODP_BUFFER_TYPE_PACKET' * @@ -92,7 +92,7 @@ static inline size_t odp_packet_buf_size(odp_packet_t pkt) /** * Helper: Tests if packet is part of a scatter/gather list * - * @param buf Packet handle + * @param pkt Packet handle * * @return 1 if belongs to a scatter list, otherwise 0 */ diff --git a/include/helper/odp_ring.h b/include/helper/odp_ring.h index 60feef3..ed58e91 100644 --- a/include/helper/odp_ring.h +++ b/include/helper/odp_ring.h @@ -124,11 +124,15 @@ enum odp_ring_queue_behavior { * a problem. */ typedef struct odp_ring { - TAILQ_ENTRY(odp_ring) next; /* Next in list. */ + /** @private Next in list. */ + TAILQ_ENTRY(odp_ring) next; - char name[ODP_RING_NAMESIZE]; /* Name of the ring. */ - int flags; /* Flags supplied at creation. */ + /** @private Name of the ring. */ + char name[ODP_RING_NAMESIZE]; + /** @private Flags supplied at creation. */ + int flags; + /** @private Producer */ struct prod { uint32_t watermark; /* Maximum items */ uint32_t sp_enqueue; /* True, if single producer. */ @@ -138,6 +142,7 @@ typedef struct odp_ring { uint32_t tail; /* Producer tail. */ } prod ODP_ALIGNED_CACHE; + /** @private Consumer */ struct cons { uint32_t sc_dequeue; /* True, if single consumer. */ uint32_t size; /* Size of the ring. */ @@ -146,7 +151,8 @@ typedef struct odp_ring { uint32_t tail; /* Consumer tail. */ } cons ODP_ALIGNED_CACHE; - void *ring[0] ODP_ALIGNED_CACHE;/* Memory space of ring starts here. */ + /** @private Memory space of ring starts here. */ + void *ring[0] ODP_ALIGNED_CACHE; } odp_ring_t; diff --git a/include/helper/odp_udp.h b/include/helper/odp_udp.h index 2d2afbc..738470e 100644 --- a/include/helper/odp_udp.h +++ b/include/helper/odp_udp.h @@ -22,15 +22,19 @@ extern "C" { #include #include +/** UDP header length */ #define ODP_UDPHDR_LEN 8 +/** UDP header */ typedef struct ODP_PACKED { - uint16be_t src_port; /**< Source port number */ - uint16be_t dst_port; /**< Destination port number */ + uint16be_t src_port; /**< Source port */ + uint16be_t dst_port; /**< Destination port */ uint16be_t length; /**< UDP datagram length in bytes (header+data) */ uint16be_t chksum; /**< UDP header and data checksum (0 if not used)*/ } odp_udphdr_t; + +/** @internal Compile time assert */ ODP_ASSERT(sizeof(odp_udphdr_t) == ODP_UDPHDR_LEN, ODP_UDPHDR_T__SIZE_ERROR); #ifdef __cplusplus diff --git a/include/odp_align.h b/include/odp_align.h index 67a7cdc..ce72f01 100644 --- a/include/odp_align.h +++ b/include/odp_align.h @@ -22,28 +22,45 @@ extern "C" { #ifdef __GNUC__ /* Checkpatch complains, but cannot use __aligned(size) for this purpose. */ + +/** + * Defines type/struct/variable alignment in bytes + */ #define ODP_ALIGNED(x) __attribute__((__aligned__(x))) +/** + * Defines type/struct to be packed + */ #define ODP_PACKED __attribute__((__packed__)) +/** + * Returns offset of member in type + */ #define ODP_OFFSETOF(type, member) __builtin_offsetof(type, member) +/** + * Returns sizeof member + */ #define ODP_FIELD_SIZEOF(type, member) sizeof(((type *)0)->member) #if defined __x86_64__ || defined __i386__ +/** Cache line size */ #define ODP_CACHE_LINE_SIZE 64 #elif defined __arm__ +/** Cache line size */ #define ODP_CACHE_LINE_SIZE 64 #elif defined __OCTEON__ +/** Cache line size */ #define ODP_CACHE_LINE_SIZE 128 #elif defined __powerpc__ +/** Cache line size */ #define ODP_CACHE_LINE_SIZE 64 #else @@ -54,7 +71,7 @@ extern "C" { #error Non-gcc compatible compiler #endif - +/** Page size */ #define ODP_PAGE_SIZE 4096 @@ -62,18 +79,38 @@ extern "C" { * Round up */ +/** + * @internal + * Round up 'x' to alignment 'align' + */ #define ODP_ALIGN_ROUNDUP(x, align)\ ((align) * (((x) + align - 1) / (align))) +/** + * @internal + * Round up pointer 'x' to alignment 'align' + */ #define ODP_ALIGN_ROUNDUP_PTR(x, align)\ ((void *)ODP_ALIGN_ROUNDUP((uintptr_t)(x), (uintptr_t)(align))) +/** + * @internal + * Round up 'x' to cache line size alignment + */ #define ODP_CACHE_LINE_SIZE_ROUNDUP(x)\ ODP_ALIGN_ROUNDUP(x, ODP_CACHE_LINE_SIZE) +/** + * @internal + * Round up pointer 'x' to cache line size alignment + */ #define ODP_CACHE_LINE_SIZE_ROUNDUP_PTR(x)\ ((void *)ODP_CACHE_LINE_SIZE_ROUNDUP((uintptr_t)(x))) +/** + * @internal + * Round up 'x' to page size alignment + */ #define ODP_PAGE_SIZE_ROUNDUP(x)\ ODP_ALIGN_ROUNDUP(x, ODP_PAGE_SIZE) @@ -82,20 +119,39 @@ extern "C" { * Round down */ +/** + * @internal + * Round down 'x' to 'align' alignment, which is a power of two + */ #define ODP_ALIGN_ROUNDDOWN_POWER_2(x, align)\ ((x) & (~((align) - 1))) +/** + * @internal + * Round down pointer 'x' to 'align' alignment, which is a power of two + */ #define ODP_ALIGN_ROUNDDOWN_PTR_POWER_2(x, align)\ ((void *)ODP_ALIGN_ROUNDDOWN_POWER_2((uintptr_t)(x), (uintptr_t)(align))) +/** + * @internal + * Round down 'x' to cache line size alignment + */ #define ODP_CACHE_LINE_SIZE_ROUNDDOWN(x)\ ODP_ALIGN_ROUNDDOWN_POWER_2(x, ODP_CACHE_LINE_SIZE) +/** + * @internal + * Round down pointer 'x' to cache line size alignment + */ #define ODP_CACHE_LINE_SIZE_ROUNDDOWN_PTR(x)\ ((void *)ODP_CACHE_LINE_SIZE_ROUNDDOWN((uintptr_t)(x))) +/** Defines type/struct/variable to be cache line size aligned */ #define ODP_ALIGNED_CACHE ODP_ALIGNED(ODP_CACHE_LINE_SIZE) + +/** Defines type/struct/variable to be page size aligned */ #define ODP_ALIGNED_PAGE ODP_ALIGNED(ODP_PAGE_SIZE) @@ -104,12 +160,16 @@ extern "C" { * Check align */ - +/** + * @internal + * Check if pointer 'x' is aligned to 'align', which is a power of two + */ #define ODP_ALIGNED_CHECK_POWER_2(x, align)\ ((((uintptr_t)(x)) & (((uintptr_t)(align))-1)) == 0) -/* - * Check value power of 2 +/** + * @internal + * Check if value is a power of two */ #define ODP_VAL_IS_POWER_2(x) ((((x)-1) & (x)) == 0) diff --git a/include/odp_barrier.h b/include/odp_barrier.h index 0a1404b..4547a26 100644 --- a/include/odp_barrier.h +++ b/include/odp_barrier.h @@ -27,8 +27,8 @@ extern "C" { * ODP execution barrier */ typedef struct odp_barrier_t { - int count; - odp_atomic_int_t bar; + int count; /**< @private Thread count */ + odp_atomic_int_t bar; /**< @private Barrier counter */ } odp_barrier_t; diff --git a/include/odp_buffer.h b/include/odp_buffer.h index d8e4779..2d2c25a 100644 --- a/include/odp_buffer.h +++ b/include/odp_buffer.h @@ -31,7 +31,7 @@ extern "C" { */ typedef uint32_t odp_buffer_t; -#define ODP_BUFFER_INVALID (0xffffffff) +#define ODP_BUFFER_INVALID (0xffffffff) /**< Invalid buffer */ /** diff --git a/include/odp_buffer_pool.h b/include/odp_buffer_pool.h index 15f0be4..8ac744a 100644 --- a/include/odp_buffer_pool.h +++ b/include/odp_buffer_pool.h @@ -23,10 +23,13 @@ extern "C" { #include #include - +/** Maximum queue name lenght in chars */ #define ODP_BUFFER_POOL_NAME_LEN 32 + +/** Invalid buffer pool */ #define ODP_BUFFER_POOL_INVALID (0xffffffff) +/** ODP buffer pool */ typedef uint32_t odp_buffer_pool_t; diff --git a/include/odp_byteorder.h b/include/odp_byteorder.h index 0450946..c573bb6 100644 --- a/include/odp_byteorder.h +++ b/include/odp_byteorder.h @@ -26,9 +26,13 @@ extern "C" { #error BYTE_ORDER not defined! #endif +/** Big endian byte order */ #define ODP_BIG_ENDIAN BIG_ENDIAN + +/** Little endian byte order */ #define ODP_LITTLE_ENDIAN LITTLE_ENDIAN +/** Selected byte order */ #if BYTE_ORDER == LITTLE_ENDIAN #define ODP_BYTE_ORDER ODP_LITTLE_ENDIAN #elif BYTE_ORDER == BIG_ENDIAN @@ -38,10 +42,14 @@ extern "C" { /* for use with type checkers such as sparse */ #ifdef __CHECKER__ +/** @internal bitwise attribute */ #define __odp_bitwise __attribute__((bitwise)) +/** @internal force attribute */ #define __odp_force __attribute__((force)) #else +/** @internal bitwise attribute */ #define __odp_bitwise +/** @internal force attribute */ #define __odp_force #endif diff --git a/include/odp_compiler.h b/include/odp_compiler.h index f4627b4..a4e6e78 100644 --- a/include/odp_compiler.h +++ b/include/odp_compiler.h @@ -18,11 +18,13 @@ extern "C" { #endif +/** @internal GNU compiler version */ #define GCC_VERSION (__GNUC__ * 10000 \ + __GNUC_MINOR__ * 100 \ + __GNUC_PATCHLEVEL__) -/* +/** + * @internal * Compiler __builtin_bswap16() is not available on all platforms * until GCC 4.8.0 - work around this by offering __odp_builtin_bswap16() * Don't use this function directly, instead see odp_byteorder.h diff --git a/include/odp_coremask.h b/include/odp_coremask.h index 3f537e1..1aeec3e 100644 --- a/include/odp_coremask.h +++ b/include/odp_coremask.h @@ -22,7 +22,7 @@ extern "C" { #include - +/** @internal */ #define ODP_COREMASK_SIZE_U64 1 /** @@ -31,7 +31,7 @@ extern "C" { * Don't access directly, use access functions. */ typedef struct odp_coremask_t { - uint64_t _u64[ODP_COREMASK_SIZE_U64]; + uint64_t _u64[ODP_COREMASK_SIZE_U64]; /**< @private Mask*/ } odp_coremask_t; diff --git a/include/odp_packet.h b/include/odp_packet.h index 0b693d9..3c7c9d0 100644 --- a/include/odp_packet.h +++ b/include/odp_packet.h @@ -26,7 +26,10 @@ extern "C" { */ typedef uint32_t odp_packet_t; +/** Invalid packet */ #define ODP_PACKET_INVALID ODP_BUFFER_INVALID + +/** Invalid offset */ #define ODP_PACKET_OFFSET_INVALID ((size_t)-1) diff --git a/include/odp_packet_io.h b/include/odp_packet_io.h index d4d05c7..b760d1d 100644 --- a/include/odp_packet_io.h +++ b/include/odp_packet_io.h @@ -27,14 +27,16 @@ extern "C" { /** ODP packet IO handle */ typedef uint32_t odp_pktio_t; + +/** Invalid packet IO handle */ #define ODP_PKTIO_INVALID 0 /** * Open an ODP packet IO instance * - * @param dev Packet IO device - * @param pool Pool to use for packet IO - * @param param Set of parameters to pass to the arch dependent implementation + * @param dev Packet IO device + * @param pool Pool to use for packet IO + * @param params Set of parameters to pass to the arch dependent implementation * * @return ODP packet IO handle or ODP_PKTIO_INVALID on error */ diff --git a/include/odp_queue.h b/include/odp_queue.h index 24ed222..24806eb 100644 --- a/include/odp_queue.h +++ b/include/odp_queue.h @@ -28,8 +28,10 @@ extern "C" { */ typedef uint32_t odp_queue_t; +/** Invalid queue */ #define ODP_QUEUE_INVALID 0 +/** Maximum queue name lenght in chars */ #define ODP_QUEUE_NAME_LEN 32 @@ -38,29 +40,39 @@ typedef uint32_t odp_queue_t; */ typedef int odp_queue_type_t; -#define ODP_QUEUE_TYPE_SCHED 0 -#define ODP_QUEUE_TYPE_POLL 1 -#define ODP_QUEUE_TYPE_PKTIN 2 -#define ODP_QUEUE_TYPE_PKTOUT 3 +#define ODP_QUEUE_TYPE_SCHED 0 /**< Scheduled queue */ +#define ODP_QUEUE_TYPE_POLL 1 /**< Not scheduled queue */ +#define ODP_QUEUE_TYPE_PKTIN 2 /**< Packet input queue */ +#define ODP_QUEUE_TYPE_PKTOUT 3 /**< Packet output queue */ /** * ODP schedule priority */ typedef int odp_schedule_prio_t; +/** Highest scheduling priority */ #define ODP_SCHED_PRIO_HIGHEST 0 + +/** Normal scheduling priority */ #define ODP_SCHED_PRIO_NORMAL (ODP_CONFIG_SCHED_PRIOS / 2) + +/** Lowest scheduling priority */ #define ODP_SCHED_PRIO_LOWEST (ODP_CONFIG_SCHED_PRIOS - 1) + +/** Default scheduling priority */ #define ODP_SCHED_PRIO_DEFAULT ODP_SCHED_PRIO_NORMAL + /** * ODP schedule synchronisation */ typedef int odp_schedule_sync_t; -#define ODP_SCHED_SYNC_NONE 0 -#define ODP_SCHED_SYNC_ATOMIC 1 -#define ODP_SCHED_SYNC_ORDERED 2 +#define ODP_SCHED_SYNC_NONE 0 /**< Queue not synchronised */ +#define ODP_SCHED_SYNC_ATOMIC 1 /**< Atomic queue */ +#define ODP_SCHED_SYNC_ORDERED 2 /**< Ordered queue */ + +/** Default queue synchronisation */ #define ODP_SCHED_SYNC_DEFAULT ODP_SCHED_SYNC_ATOMIC /** @@ -68,10 +80,18 @@ typedef int odp_schedule_sync_t; */ typedef int odp_schedule_group_t; +/** Group of all cores */ #define ODP_SCHED_GROUP_ALL 0 + +/** Default core group */ #define ODP_SCHED_GROUP_DEFAULT ODP_SCHED_GROUP_ALL + +/** + * ODP Queue parameters + */ typedef union odp_queue_param_t { + /** Scheduler parameters */ struct { odp_schedule_prio_t prio; odp_schedule_sync_t sync; diff --git a/include/odp_shared_memory.h b/include/odp_shared_memory.h index 11e1c2f..28b650d 100644 --- a/include/odp_shared_memory.h +++ b/include/odp_shared_memory.h @@ -21,7 +21,7 @@ extern "C" { #include - +/** Maximum shared memory block name lenght in chars */ #define ODP_SHM_NAME_LEN 32 diff --git a/include/odp_spinlock.h b/include/odp_spinlock.h index e489663..f25d068 100644 --- a/include/odp_spinlock.h +++ b/include/odp_spinlock.h @@ -26,7 +26,7 @@ extern "C" { * ODP spinlock */ typedef struct odp_spinlock_t { - volatile int lock; + volatile int lock; /**< @private Lock */ } odp_spinlock_t; diff --git a/include/odp_sync.h b/include/odp_sync.h index 3d347e4..e5bd0fb 100644 --- a/include/odp_sync.h +++ b/include/odp_sync.h @@ -19,6 +19,12 @@ extern "C" { #endif +/** + * Synchronise stores + * + * Ensures that all CPU store operations that precede the odp_sync_stores() + * call are globally visible before any store operation that follows it. + */ static inline void odp_sync_stores(void) { #if defined __x86_64__ || defined __i386__ diff --git a/include/odp_ticketlock.h b/include/odp_ticketlock.h index 9cf76de..6277a18 100644 --- a/include/odp_ticketlock.h +++ b/include/odp_ticketlock.h @@ -27,8 +27,8 @@ extern "C" { * ODP ticketlock */ typedef struct odp_ticketlock_t { - odp_atomic_u32_t next_ticket; - volatile uint32_t cur_ticket; + odp_atomic_u32_t next_ticket; /**< @private Next ticket */ + volatile uint32_t cur_ticket; /**< @private Current ticket */ } odp_ticketlock_t; diff --git a/include/odp_timer.h b/include/odp_timer.h index 0b6dc51..80babd1 100644 --- a/include/odp_timer.h +++ b/include/odp_timer.h @@ -29,6 +29,7 @@ extern "C" { */ typedef uint32_t odp_timer_t; +/** Invalid timer */ #define ODP_TIMER_INVALID 0 @@ -37,6 +38,7 @@ typedef uint32_t odp_timer_t; */ typedef odp_buffer_t odp_timer_tmo_t; +/** Invalid timeout */ #define ODP_TIMER_TMO_INVALID 0 diff --git a/include/odp_version.h b/include/odp_version.h index e9bb154..152b329 100644 --- a/include/odp_version.h +++ b/include/odp_version.h @@ -45,10 +45,13 @@ extern "C" { #define ODP_VERSION_API_BUG 1 - +/** @internal Version string expand */ #define ODP_VERSION_STR_EXPAND(x) #x + +/** @internal Version to string */ #define ODP_VERSION_TO_STR(x) ODP_VERSION_STR_EXPAND(x) +/** @internal API version string */ #define ODP_VERSION_API_STR \ ODP_VERSION_TO_STR(ODP_VERSION_API_MAIN) "."\ ODP_VERSION_TO_STR(ODP_VERSION_API_SUB) "."\ diff --git a/platform/linux-generic/Doxyfile.in b/platform/linux-generic/Doxyfile.in index 421e7ac..661924b 100644 --- a/platform/linux-generic/Doxyfile.in +++ b/platform/linux-generic/Doxyfile.in @@ -28,3 +28,5 @@ EXAMPLE_PATTERNS = *.c EXAMPLE_RECURSIVE = YES IMAGE_PATH = ../../doc/images HTML_EXTRA_STYLESHEET = ../../doc/odpdoxygen.css +PREDEFINED = __GNUC__ +INTERNAL_DOCS = YES diff --git a/test/example/odp_example.c b/test/example/odp_example.c index 4764657..d676bf7 100644 --- a/test/example/odp_example.c +++ b/test/example/odp_example.c @@ -26,40 +26,42 @@ #include -#define MAX_WORKERS 32 -#define MSG_POOL_SIZE (4*1024*1024) -#define MAX_ALLOCS 35 -#define QUEUES_PER_PRIO 64 -#define QUEUE_ROUNDS (512*1024) -#define ALLOC_ROUNDS (1024*1024) -#define MULTI_BUFS_MAX 4 -#define SCHED_RETRY 100 -#define TEST_SEC 2 - - +#define MAX_WORKERS 32 /**< Max worker threads */ +#define MSG_POOL_SIZE (4*1024*1024) /**< Message pool size */ +#define MAX_ALLOCS 35 /**< Alloc burst size */ +#define QUEUES_PER_PRIO 64 /**< Queue per priority */ +#define QUEUE_ROUNDS (512*1024) /**< Queue test rounds */ +#define ALLOC_ROUNDS (1024*1024) /**< Alloc test rounds */ +#define MULTI_BUFS_MAX 4 /**< Buffer burst size */ +#define SCHED_RETRY 100 /**< Schedule retries */ +#define TEST_SEC 2 /**< Time test duration in sec */ + +/** Dummy message */ typedef struct { - int msg_id; - int seq; + int msg_id; /**< Message ID */ + int seq; /**< Sequence number */ } test_message_t; -#define MSG_HELLO 1 -#define MSG_ACK 2 - +#define MSG_HELLO 1 /**< Hello */ +#define MSG_ACK 2 /**< Ack */ +/** Test arguments */ typedef struct { - int core_count; + int core_count; /**< Core count*/ } test_args_t; +/** @private Barrier for test synchronisation */ static odp_barrier_t test_barrier; + /* #define TEST_TIMEOUTS */ #ifdef TEST_TIMEOUTS static odp_timer_t test_timer; #endif -/* - * Clear all scheduled queues. Retry to be sure that all +/** + * @internal Clear all scheduled queues. Retry to be sure that all * buffers have been scheduled. */ static void clear_sched_queues(void) @@ -119,8 +121,13 @@ static void test_timeouts(int thr) } #endif -/* - * Test single buffer alloc and free +/** + * @internal Test single buffer alloc and free + * + * @param thr Thread + * @param pool Buffer pool + * + * @return 0 if successful */ static int test_alloc_single(int thr, odp_buffer_pool_t pool) { @@ -151,8 +158,13 @@ static int test_alloc_single(int thr, odp_buffer_pool_t pool) return 0; } -/* - * Test multiple buffers alloc and free +/** + * @internal Test multiple buffers alloc and free + * + * @param thr Thread + * @param pool Buffer pool + * + * @return 0 if successful */ static int test_alloc_multi(int thr, odp_buffer_pool_t pool) { @@ -187,10 +199,15 @@ static int test_alloc_multi(int thr, odp_buffer_pool_t pool) return 0; } -/* - * Test queue polling +/** + * @internal Test queue polling * * Enqueue to and dequeue to/from a single shared queue. + * + * @param thr Thread + * @param msg_pool Buffer pool + * + * @return 0 if successful */ static int test_poll_queue(int thr, odp_buffer_pool_t msg_pool) { @@ -248,11 +265,18 @@ static int test_poll_queue(int thr, odp_buffer_pool_t msg_pool) return 0; } -/* - * Test scheduling of a single queue +/** + * @internal Test scheduling of a single queue * * Enqueue a buffer to the shared queue. Schedule and enqueue the received * buffer back into the queue. + * + * @param str Test case name string + * @param thr Thread + * @param msg_pool Buffer pool + * @param prio Priority + * + * @return 0 if successful */ static int test_sched_single_queue(const char *str, int thr, odp_buffer_pool_t msg_pool, int prio) @@ -324,11 +348,18 @@ static int test_sched_single_queue(const char *str, int thr, return 0; } -/* - * Test scheduling of multiple queues +/** + * @internal Test scheduling of multiple queues * * Enqueue a buffer to each queue. Schedule and enqueue the received * buffer back into the queue it came from. + * + * @param str Test case name string + * @param thr Thread + * @param msg_pool Buffer pool + * @param prio Priority + * + * @return 0 if successful */ static int test_sched_multi_queue(const char *str, int thr, odp_buffer_pool_t msg_pool, int prio) @@ -407,7 +438,16 @@ static int test_sched_multi_queue(const char *str, int thr, return 0; } - +/** + * @internal Test scheduling of multiple queues with multi_sched and multi_enq + * + * @param str Test case name string + * @param thr Thread + * @param msg_pool Buffer pool + * @param prio Priority + * + * @return 0 if successful + */ static int test_sched_multi_queue_m(const char *str, int thr, odp_buffer_pool_t msg_pool, int prio) { @@ -491,6 +531,13 @@ static int test_sched_multi_queue_m(const char *str, int thr, return 0; } +/** + * @internal Worker thread + * + * @param arg Arguments + * + * @return NULL on failure + */ static void *run_thread(void *arg) { int thr; @@ -580,7 +627,9 @@ static void *run_thread(void *arg) return arg; } - +/** + * @internal Test cycle counter accuracy + */ static void test_time(void) { struct timespec tp1, tp2; @@ -635,7 +684,9 @@ static void test_time(void) printf("\n"); } - +/** + * @internal Print help + */ static void print_usage(void) { printf("\n\nUsage: ./odp_example [options]\n"); @@ -645,7 +696,13 @@ static void print_usage(void) printf("\n\n"); } - +/** + * @internal Parse arguments + * + * @param argc Argument count + * @param argv Argument vector + * @param args Test arguments + */ static void parse_args(int argc, char *argv[], test_args_t *args) { int opt; @@ -680,6 +737,9 @@ static void parse_args(int argc, char *argv[], test_args_t *args) } +/** + * Test main function + */ int main(int argc, char *argv[]) { odp_linux_pthread_t thread_tbl[MAX_WORKERS];