From 764a91254880d63f4e2ea9e69ed6e4b5afc4b617 Mon Sep 17 00:00:00 2001 From: Vojtech Vilimek Date: Tue, 20 Aug 2024 12:48:20 +0200 Subject: [PATCH] SNMP: Programmer documentation --- proto/snmp/mib_tree.c | 61 +++++++++++++++++++++++++++++++---------- proto/snmp/snmp_utils.c | 57 ++++++++++++++++++++++++++++++-------- proto/snmp/subagent.c | 10 +++---- 3 files changed, 97 insertions(+), 31 deletions(-) diff --git a/proto/snmp/mib_tree.c b/proto/snmp/mib_tree.c index 03f942e9..1054f21e 100644 --- a/proto/snmp/mib_tree.c +++ b/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) { diff --git a/proto/snmp/snmp_utils.c b/proto/snmp/snmp_utils.c index c5766717..0a795daf 100644 --- a/proto/snmp/snmp_utils.c +++ b/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) { diff --git a/proto/snmp/subagent.c b/proto/snmp/subagent.c index b61f819b..e28e3317 100644 --- a/proto/snmp/subagent.c +++ b/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 *