From e12086c98029f930a4e7f608b505c56c39ad2d07 Mon Sep 17 00:00:00 2001 From: adamdunkels Date: Sun, 25 Mar 2007 12:05:51 +0000 Subject: [PATCH] Documentation fixes --- core/net/rime/abc.c | 4 +-- core/net/rime/abc.h | 47 ++++++++++++++++++++-------- core/net/rime/ctimer.c | 4 +-- core/net/rime/ctimer.h | 4 +-- core/net/rime/ibc.c | 10 ++++-- core/net/rime/ibc.h | 65 +++++++++++++++++++++++++++++++++++++-- core/net/rime/mesh.h | 66 ++++++++++++++++++++++++++++++++++++++-- core/net/rime/queuebuf.h | 18 +++++++++-- core/net/rime/uibc.h | 4 +-- 9 files changed, 192 insertions(+), 30 deletions(-) diff --git a/core/net/rime/abc.c b/core/net/rime/abc.c index 4e5bb3b2c..cf6aea0a6 100644 --- a/core/net/rime/abc.c +++ b/core/net/rime/abc.c @@ -30,11 +30,11 @@ * * Author: Adam Dunkels * - * $Id: abc.c,v 1.8 2007/03/23 10:46:35 adamdunkels Exp $ + * $Id: abc.c,v 1.9 2007/03/25 12:05:51 adamdunkels Exp $ */ /** - * \addtogroup rime + * \addtogroup rime_abc * @{ */ diff --git a/core/net/rime/abc.h b/core/net/rime/abc.h index 108d20aaa..0a5c274fb 100644 --- a/core/net/rime/abc.h +++ b/core/net/rime/abc.h @@ -1,3 +1,16 @@ +/** + * \addtogroup rime + * @{ + */ + +/** + * \defgroup rime_abc Anonymous best-effort local area broadcast (abc) + * @{ + * + * The abc module sends packets to all local area neighbors without + * any extra headers that idendtify the sender or receiver. + */ + /* * Copyright (c) 2006, Swedish Institute of Computer Science. * All rights reserved. @@ -28,14 +41,8 @@ * * This file is part of the Contiki operating system. * - * $Id: abc.h,v 1.7 2007/03/19 22:10:16 adamdunkels Exp $ + * $Id: abc.h,v 1.8 2007/03/25 12:05:51 adamdunkels Exp $ */ - -/** - * \addtogroup rime - * @{ - */ - /** * \file * Header file for the Rime module Anonymous BroadCast (abc) @@ -51,7 +58,12 @@ struct abc_conn; +/** + * \brief Callback structure for abc + * + */ struct abc_callbacks { + /** Called when a packet has been received by the abc module. */ void (* recv)(struct abc_conn *ptr); }; @@ -80,6 +92,16 @@ struct abc_conn { void abc_open(struct abc_conn *c, u16_t channel, const struct abc_callbacks *u); +/** + * \brief Close an abc connection + * \param c A pointer to a struct abc_conn + * + * This function closes an abc connection that has + * previously been opened with abc_open(). + * + * This function typically is called as an exit handler. + * + */ void abc_close(struct abc_conn *c); /** @@ -98,14 +120,15 @@ void abc_close(struct abc_conn *c); int abc_send(struct abc_conn *c); /** - * \brief Pass a packet to the abc layer + * \brief Internal Rime function: Pass a packet to the abc layer + * + * This function is used internally by Rime to pass + * packets to the abc layer. Should never be called + * directly. * - * This function is used by a device driver to pass an - * incoming packet to the abc layer. The packet must be - * present in the rimebuf buffer when this function is - * called. */ void abc_input_packet(void); #endif /* __BC_H__ */ /** @} */ +/** @} */ diff --git a/core/net/rime/ctimer.c b/core/net/rime/ctimer.c index aa1ff2038..63601ee17 100644 --- a/core/net/rime/ctimer.c +++ b/core/net/rime/ctimer.c @@ -28,12 +28,12 @@ * * This file is part of the Contiki operating system. * - * $Id: ctimer.c,v 1.1 2007/02/28 16:38:51 adamdunkels Exp $ + * $Id: ctimer.c,v 1.2 2007/03/25 12:05:51 adamdunkels Exp $ */ /** * \file - * A brief description of what this file is. + * Callback timer implementation * \author * Adam Dunkels */ diff --git a/core/net/rime/ctimer.h b/core/net/rime/ctimer.h index 2ffeed6f2..07843e057 100644 --- a/core/net/rime/ctimer.h +++ b/core/net/rime/ctimer.h @@ -28,12 +28,12 @@ * * This file is part of the Contiki operating system. * - * $Id: ctimer.h,v 1.1 2007/02/28 16:38:51 adamdunkels Exp $ + * $Id: ctimer.h,v 1.2 2007/03/25 12:05:51 adamdunkels Exp $ */ /** * \file - * Module which calls a function after a time + * Header file for the callback timer * \author * Adam Dunkels */ diff --git a/core/net/rime/ibc.c b/core/net/rime/ibc.c index c89317eb4..5f4ac90b0 100644 --- a/core/net/rime/ibc.c +++ b/core/net/rime/ibc.c @@ -1,3 +1,8 @@ +/** + * \addtogroup rime-ibc + * @{ + */ + /* * Copyright (c) 2006, Swedish Institute of Computer Science. * All rights reserved. @@ -28,12 +33,12 @@ * * This file is part of the Contiki operating system. * - * $Id: ibc.c,v 1.7 2007/03/23 10:46:35 adamdunkels Exp $ + * $Id: ibc.c,v 1.8 2007/03/25 12:05:51 adamdunkels Exp $ */ /** * \file - * A brief description of what this file is. + * Identified best-effort local area broadcast (ibc) * \author * Adam Dunkels */ @@ -89,3 +94,4 @@ ibc_send(struct ibc_conn *c) return 0; } /*---------------------------------------------------------------------------*/ +/** @} */ diff --git a/core/net/rime/ibc.h b/core/net/rime/ibc.h index 9841e4475..7f8607468 100644 --- a/core/net/rime/ibc.h +++ b/core/net/rime/ibc.h @@ -1,3 +1,16 @@ +/** + * \addtogroup rime + * @{ + */ + +/** + * \defgroup rime-ibc Identified best-effort local area broadcast (ibc) + * @{ + * + * The ibc module sends packets to all local area neighbors with an a + * header that identifies the sender. + */ + /* * Copyright (c) 2006, Swedish Institute of Computer Science. * All rights reserved. @@ -28,12 +41,12 @@ * * This file is part of the Contiki operating system. * - * $Id: ibc.h,v 1.5 2007/03/19 22:10:16 adamdunkels Exp $ + * $Id: ibc.h,v 1.6 2007/03/25 12:05:51 adamdunkels Exp $ */ /** * \file - * A brief description of what this file is. + * Header file for identified best-effort local area broadcast * \author * Adam Dunkels */ @@ -46,7 +59,12 @@ struct ibc_conn; +/** + * \brief Callback structure for abc + * + */ struct ibc_callbacks { + /** Called when a packet has been received by the ibc module. */ void (* recv)(struct ibc_conn *ptr, rimeaddr_t *sender); }; @@ -55,9 +73,52 @@ struct ibc_conn { const struct ibc_callbacks *u; }; +/** + * \brief Set up an identified best-effort broadcast connection + * \param c A pointer to a struct ibc_conn + * \param channel The channel on which the connection will operate + * \param u A struct ibc_callbacks with function pointers to functions that will be called when a packet has been received + * + * This function sets up an ibc connection on the + * specified channel. The caller must have allocated the + * memory for the struct ibc_conn, usually by declaring it + * as a static variable. + * + * The struct ibc_callbacks pointer must point to a structure + * containing a pointer to a function that will be called + * when a packet arrives on the channel. + * + */ void ibc_open(struct ibc_conn *c, u16_t channel, const struct ibc_callbacks *u); + +/** + * \brief Close an ibc connection + * \param c A pointer to a struct ibc_conn + * + * This function closes an ibc connection that has + * previously been opened with ibc_open(). + * + * This function typically is called as an exit handler. + * + */ void ibc_close(struct ibc_conn *c); + +/** + * \brief Send an anonymous best-effort broadcast packet + * \param c The ibc connection on which the packet should be sent + * \retval Non-zero if the packet could be sent, zero otherwise + * + * This function sends an anonymous best-effort broadcast + * packet. The packet must be present in the rimebuf + * before this function is called. + * + * The parameter c must point to an abc connection that + * must have previously been set up with ibc_open(). + * + */ int ibc_send(struct ibc_conn *c); #endif /* __IBC_H__ */ +/** @} */ +/** @} */ diff --git a/core/net/rime/mesh.h b/core/net/rime/mesh.h index eaac3313e..94d448473 100644 --- a/core/net/rime/mesh.h +++ b/core/net/rime/mesh.h @@ -1,3 +1,17 @@ +/** + * \addtogroup rime + * @{ + */ + +/** + * \defgroup rime-mesh Mesh routing + * @{ + * + * The abc module sends packets using multi-hop routing to a specified + * receiver somewhere in the network. + * + */ + /* * Copyright (c) 2007, Swedish Institute of Computer Science. * All rights reserved. @@ -28,7 +42,7 @@ * * This file is part of the Contiki operating system. * - * $Id: mesh.h,v 1.5 2007/03/22 17:34:16 adamdunkels Exp $ + * $Id: mesh.h,v 1.6 2007/03/25 12:05:51 adamdunkels Exp $ */ /** @@ -47,9 +61,15 @@ struct mesh_conn; +/** + * \brief Mesh callbacks + */ struct mesh_callbacks { + /** Called when a packet is received. */ void (* recv)(struct mesh_conn *c, rimeaddr_t *from); + /** Called when a packet, sent with mesh_send(), is actually transmitted. */ void (* sent)(struct mesh_conn *c); + /** Called when a packet, sent with mesh_send(), times out and is dropped. */ void (* timedout)(struct mesh_conn *c); }; @@ -61,11 +81,51 @@ struct mesh_conn { const struct mesh_callbacks *cb; }; +/** + * \brief Open a mesh connection + * \param c A pointer to a struct mesh_conn + * \param channels The channels on which the connection will operate; mesh uses 3 channels + * \param callbacks Pointer to callback structure + * + * This function sets up a mesh connection on the + * specified channel. The caller must have allocated the + * memory for the struct mesh_conn, usually by declaring it + * as a static variable. + * + * The struct mesh_callbacks pointer must point to a structure + * containing function pointers to functions that will be called + * when a packet arrives on the channel. + * + */ void mesh_open(struct mesh_conn *c, u16_t channels, const struct mesh_callbacks *callbacks); -int mesh_send(struct mesh_conn *c, rimeaddr_t *dest); - +/** + * \brief Close an mesh connection + * \param c A pointer to a struct mesh_conn + * + * This function closes an mesh connection that has + * previously been opened with mesh_open(). + * + * This function typically is called as an exit handler. + * + */ void mesh_close(struct mesh_conn *c); +/** + * \brief Send a mesh packet + * \param c The mesh connection on which the packet should be sent + * \retval Non-zero if the packet could be queued for sending, zero otherwise + * + * This function sends a mesh packet. The packet must be + * present in the rimebuf before this function is called. + * + * The parameter c must point to an abc connection that + * must have previously been set up with mesh_open(). + * + */ +int mesh_send(struct mesh_conn *c, rimeaddr_t *dest); + #endif /* __MESH_H__ */ +/** @} */ +/** @} */ diff --git a/core/net/rime/queuebuf.h b/core/net/rime/queuebuf.h index 0ae9aa5a5..a351b4a98 100644 --- a/core/net/rime/queuebuf.h +++ b/core/net/rime/queuebuf.h @@ -1,3 +1,16 @@ +/** + * \addtogroup rime + * @{ + */ + +/** + * \defgroup rime-queuebuf Rime queue buffer management + * @{ + * + * The Rime queue buffer management handles buffers that are queued. + * + */ + /* * Copyright (c) 2006, Swedish Institute of Computer Science. * All rights reserved. @@ -28,12 +41,12 @@ * * This file is part of the Contiki operating system. * - * $Id: queuebuf.h,v 1.2 2007/03/20 12:26:23 adamdunkels Exp $ + * $Id: queuebuf.h,v 1.3 2007/03/25 12:07:10 adamdunkels Exp $ */ /** * \file - * A brief description of what this file is. + * Header file for the Rime queue buffer management * \author * Adam Dunkels */ @@ -49,7 +62,6 @@ void queuebuf_init(void); struct queuebuf *queuebuf_new_from_rimebuf(void); void queuebuf_free(struct queuebuf *b); -void queuebuf_from_rimebuf(struct queuebuf *b); void queuebuf_to_rimebuf(struct queuebuf *b); void *queuebuf_dataptr(struct queuebuf *b); diff --git a/core/net/rime/uibc.h b/core/net/rime/uibc.h index bbfff4626..31b0d3806 100644 --- a/core/net/rime/uibc.h +++ b/core/net/rime/uibc.h @@ -4,7 +4,7 @@ */ /** - * \defgroup uibc Unique Identified best effort local area BroadCast + * \defgroup rime_uibc Unique Identified best effort local area Broadcast * @{ * * Send one packet that is unique within a time interval. @@ -41,7 +41,7 @@ * * This file is part of the Contiki operating system. * - * $Id: uibc.h,v 1.1 2007/03/21 23:21:01 adamdunkels Exp $ + * $Id: uibc.h,v 1.2 2007/03/25 12:07:10 adamdunkels Exp $ */ /**