SNMP: Programmer documentation

proto/snmp/mib_tree.c

@@ -27,7 +27,7 @@ mib_mb_realloc(pool *p, void *ptr, unsigned size)
   return mb_realloc(ptr, size);
 }
 
-/*
+/**
  * mib_tree_init - Initialize a MIB tree
  * @p: allocation source pool
  * @t: pointer to a tree being initialized
@@ -57,6 +57,13 @@ mib_tree_init(pool *p, struct mib_tree *t)
   (void) mib_tree_add(p, t, oid, 0);
 }
 
+/**
+ * mib_tree_hint - preallocate child array for given OID
+ * @p: memory pool to allocated from
+ * @t: MIB tree to hint
+ * @oid: MIB subtree root with upto @size children
+ * @size: number of children in @oid subtree
+ */
 int
 mib_tree_hint(pool *p, struct mib_tree *t, const struct oid *oid, uint size)
 {
@@ -78,12 +85,7 @@ mib_tree_hint(pool *p, struct mib_tree *t, const struct oid *oid, uint size)
   return 1;
 }
 
-
-// TODO: This function does not work with leaf nodes inside the snmp_internet prefix
-// area
-// Return NULL of failure, valid mib_node_u pointer otherwise
-
-/*
+/**
  * mib_tree_add - Insert a new node to the tree
  * @p: allocation source pool
  * @t: MIB tree to insert to
@@ -99,6 +101,7 @@ mib_tree_hint(pool *p, struct mib_tree *t, const struct oid *oid, uint size)
 mib_node_u *
 mib_tree_add(pool *p, struct mib_tree *t, const struct oid *oid, int is_leaf)
 {
+  // TODO may not function properly in snmp_internet prefix region
   struct mib_walk_state walk;
   mib_node_u *node;
 
@@ -248,7 +251,7 @@ mib_tree_add(pool *p, struct mib_tree *t, const struct oid *oid, int is_leaf)
   return last;
 }
 
-/*
+/**
  * mib_tree_delete - delete a MIB subtree
  * @t: MIB tree
  * @walk: MIB tree walk state that specify the subtree
@@ -370,7 +373,7 @@ continue_while:	  /* like outer continue, but skip always true condition */
   return deleted;
 }
 
-/*
+/**
  * mib_tree_remove - delete a MIB subtree
  * @t: MIB tree
  * @oid: object identifier specifying the subtree
@@ -392,7 +395,7 @@ mib_tree_remove(struct mib_tree *t, const struct oid *oid)
   return mib_tree_delete(t, &walk);
 }
 
-/*
+/**
  * mib_tree_find - Find a OID node in MIB tree
  * @t: searched tree
  * @walk: output search state
@@ -549,6 +552,11 @@ mib_tree_find(const struct mib_tree *t, struct mib_walk_state *walk, const struc
   return walk->stack[walk->stack_pos++] = node;
 }
 
+/**
+ * mib_tree_walk_init - Initialize MIB tree walk state
+ * @walk: MIB tree walk state to init
+ * @t: optional MIB tree
+ */
 void
 mib_tree_walk_init(struct mib_walk_state *walk, const struct mib_tree *t)
 {
@@ -560,6 +568,12 @@ mib_tree_walk_init(struct mib_walk_state *walk, const struct mib_tree *t)
     walk->stack[0] = (mib_node_u *) &t->root;
 }
 
+/*
+ * walk_is_prefixable - test prefixability of MIB walk state
+ * @walk: MIB tree walk state to use
+ *
+ * This function is functionally equivalent to snmp_oid_is_prefixable().
+ */
 static inline int
 walk_is_prefixable(const struct mib_walk_state *walk)
 {
@@ -577,6 +591,14 @@ walk_is_prefixable(const struct mib_walk_state *walk)
   return id > 0 && id <= UINT8_MAX;
 }
 
+/*
+ * mib_tree_walk_to_oid - retrieve OID from MIB tree walk state
+ * @walk: MIB tree walk state to transform
+ * @result: destination OID
+ * @subids: Maximal number of subids in available space
+ *
+ * Return 1 if the space is insufficient, 0 otherwise.
+ */
 int
 mib_tree_walk_to_oid(const struct mib_walk_state *walk, struct oid *result, u32 subids)
 {
@@ -625,12 +647,12 @@ mib_tree_walk_to_oid(const struct mib_walk_state *walk, struct oid *result, u32
 }
 
 /*
- * return -1 if walk_oid < oid
- * return 0 if walk_oid == oid
- * return +1 if walk_oid > oid
+ * mib_tree_walk_oid_compare - compare MIB tree walk state and OID
+ * @walk: left relation operand
+ * @oid: Object Identifier in cpu native byte order
  *
+ * Return value semantics is the same as snmp_oid_compare().
  */
-// TODO tests, doc string
 int
 mib_tree_walk_oid_compare(const struct mib_walk_state *walk, const struct oid *oid)
 {
@@ -741,6 +763,11 @@ mib_tree_walk_is_oid_descendant(const struct mib_walk_state *walk, const struct
   }
 }
 
+/**
+ * mib_tree_walk_next - find MIB tree node successor in lexicagraphically ordered MIB tree
+ * @t: MIB tree to use
+ * @walk: MIB tree walk state to use
+ */
 mib_node_u *
 mib_tree_walk_next(const struct mib_tree *t, struct mib_walk_state *walk)
 {
@@ -789,6 +816,12 @@ mib_tree_walk_next(const struct mib_tree *t, struct mib_walk_state *walk)
   return NULL;
 }
 
+/**
+ * mib_tree_walk_next_leaf - wrapper around mib_tree_walk_next returning only leafs
+ * @t: MIB tree to use
+ * @walk: MIB tree walk state
+ * @skip: lower value bound for next OID id
+ */
 struct mib_leaf *
 mib_tree_walk_next_leaf(const struct mib_tree *t, struct mib_walk_state *walk, u32 skip)
 {

proto/snmp/snmp_utils.c

@@ -23,7 +23,7 @@ snmp_pdu_context(struct snmp_pdu *pdu, struct snmp_proto *p, sock *sk)
   pdu->sr_o_end = NULL;
 }
 
-/**
+/*
  * snmp_session - store packet ids from protocol to header
  * @p: source SNMP protocol instance
  * @h: dest PDU header
@@ -43,7 +43,7 @@ snmp_varbind_data(const struct agentx_varbind *vb)
   return (void *) &vb->name + name_size;
 }
 
-/**
+/*
  * snmp_is_oid_empty - check if oid is null-valued
  * @oid: object identifier to check
  *
@@ -133,7 +133,7 @@ snmp_oid_to_buf(struct oid *dst, const struct oid *src)
     STORE_U32(dst->ids[i], src->ids[i]);
 }
 
-/**
+/*
  * snmp_str_size_from_len - return in-buffer octet string size
  * @len: length of C-string, returned from strlen()
  */
@@ -143,7 +143,7 @@ snmp_str_size_from_len(uint len)
   return 4 + BIRD_ALIGN(len, 4);
 }
 
-/**
+/*
  * snmp_str_size - return in packet size of supplied string
  * @str: measured string
  *
@@ -156,7 +156,7 @@ snmp_str_size(const char *str)
   return snmp_str_size_from_len(strlen(str));
 }
 
-/**
+/*
  * snmp_oid_size - measure size of OID in bytes
  * @o: object identifier to use
  *
@@ -185,7 +185,7 @@ snmp_get_octet_size(const struct agentx_octet_str *str)
   return str->length;
 }
 
-/**
+/*
  * snmp_varbind_header_size - measure size of VarBind without data in bytes
  * @vb_name: VarBind OID name
  *
@@ -230,7 +230,7 @@ snmp_varbind_size_unsafe(const struct agentx_varbind *vb)
   }
 }
 
-/**
+/*
  * snmp_varbind_size_from_len - get size in-buffer VarBind for known OID and data
  * @n_subid: number of subidentifiers of the VarBind's OID name
  * @type: type of VarBind
@@ -282,7 +282,7 @@ snmp_test_varbind_type(u16 type)
 }
 
 
-/**
+/*
  * snmp_valid_ip4_index - check IPv4 address validity in oid
  * @o: object identifier holding ip address
  * @start: index of first address id
@@ -296,7 +296,7 @@ snmp_valid_ip4_index(const struct oid *o, uint start)
     return 0;
 }
 
-/**
+/*
  * snmp_valid_ip4_index_unsafe - check validity of IPv4 address in oid
  * @o: object identifier holding ip address
  * @start: index of first address id
@@ -337,7 +337,7 @@ snmp_put_nstr(byte *buf, const char *str, uint len)
   return buf + (alen - len);
 }
 
-/**
+/*
  * snmp_put_str - put string into SNMP PDU transcieve buffer
  * @buf: pointer to first unoccupied buffer byte
  * @str: string to place
@@ -373,7 +373,7 @@ snmp_put_blank(byte *buf)
   return buf + 4;
 }
 
-/**
+/*
  * snmp_put_fbyte - put one padded byte to SNMP PDU transcieve buffer
  * @buf: pointer to free buffer byte
  * @data: byte to use
@@ -709,7 +709,7 @@ snmp_oid_log(const struct oid *oid)
  * viewed as longest common prefix. Note that if both @left and @right are
  * prefixable but not prefixed the result in @out will also not be prefixed.
  *
- * This function is used intensively by snmp_test.c.
+ * This function is used intensively by |snmp_test.c|.
  */
 void
 snmp_oid_common_ancestor(const struct oid *left, const struct oid *right, struct oid *out)
@@ -801,6 +801,18 @@ snmp_oid_common_ancestor(const struct oid *left, const struct oid *right, struct
 /*
  * SNMP MIB tree walking
  */
+
+/**
+ * snmp_walk_init - Try to find exactly matching OID packat VarBind in MIB tree
+ * @tree: MIB tree to use
+ * @walk: MIB tree walk state storage
+ * @c: AgentX PDU creation context
+ *
+ * Populate the @walk state and try to find MIB tree leaf equivalent to
+ * c->sr_vb_start which is requested VarBind to fill based on it's OID name.
+ * Return value is either pointer to valid MIB tree leaf or NULL if no leaf
+ * matched.
+ */
 struct mib_leaf *
 snmp_walk_init(struct mib_tree *tree, struct mib_walk_state *walk, struct snmp_pdu *c)
 {
@@ -816,6 +828,15 @@ snmp_walk_init(struct mib_tree *tree, struct mib_walk_state *walk, struct snmp_p
   return (!node || !mib_node_is_leaf(node)) ? NULL : &node->leaf;
 }
 
+/**
+ * snmp_walk_next - wrapper around MIB tree mib_walk_next() for single call
+ * @tree: MIB tree to use
+ * @walk: MIB tree walk state storage
+ * @c: AgentX PDU creation context
+ *
+ * The snmp_walk_next() function searches MIB tree with updates of the VarBind
+ * OID name with.
+ */
 struct mib_leaf *
 snmp_walk_next(struct mib_tree *tree, struct mib_walk_state *walk, struct snmp_pdu *c)
 {
@@ -881,6 +902,18 @@ snmp_walk_next(struct mib_tree *tree, struct mib_walk_state *walk, struct snmp_p
   return leaf;
 }
 
+/**
+ * snmp_walk_fill - fill current VarBind by filler hook invocation
+ * @leaf: MIB tree leaf with filler hook
+ * @walk: MIB tree walk state
+ * @c: AgentX PDU creation context
+ *
+ * The function takes responsibility for VarBind type setting (for known VB
+ * types) and for buffer space allocated for VarBind data (based on type or
+ * configured size). This simplifies code of filler hooks in most cases.
+ * We also allow the @leaf to be NULL, in which case we set the VarBind to
+ * error type noSuchObject.
+ */
 enum snmp_search_res
 snmp_walk_fill(struct mib_leaf *leaf, struct mib_walk_state *walk, struct snmp_pdu *c)
 {

proto/snmp/subagent.c

@@ -932,8 +932,8 @@ snmp_get_bulk_pdu(struct snmp_proto *p, struct snmp_pdu *c, struct mib_walk_stat
   //bulk->has_any |= snmp_get_next_pdu(p, c, walk);
 }
 
-/*
- * parse_gets_pdu - parse received gets PDUs
+/**
+ * parse_gets_pdu - common parsing of received gets PDUs
  * @p: SNMP protocol instance
  * @pkt_start: pointer to first byte of received PDU
  *
@@ -1312,7 +1312,7 @@ snmp_register_ack(struct snmp_proto *p, struct agentx_response *res)
     snmp_up(p);
 }
 
-/*
+/**
  * snmp_stop_subagent - close established session
  * @p: SNMP protocol instance
  *
@@ -1326,7 +1326,7 @@ snmp_stop_subagent(struct snmp_proto *p)
   close_pdu(p, AGENTX_CLOSE_SHUTDOWN);
 }
 
-/*
+/**
  * snmp_register_mibs - register all MIB subtrees
  * @p: SNMP protocol instance
  */
@@ -1337,7 +1337,7 @@ snmp_register_mibs(struct snmp_proto *p)
   ASSUME(!EMPTY_LIST(p->registration_queue));
 }
 
-/*
+/**
  * snmp_start_subagent - send session open request
  * @p: SNMP protocol instance
  *