ng_pktbuf: simplify API by extension

This simplifies the `ng_pktbuf` API by adding a new function
`ng_pktbuf_mark()` which takes over some functionality of
`ng_pktbuf_add()`. `size == 0` for `ng_pktbuf_add()` is now illegal.

sys/include/net/ng_pktbuf.h

@@ -56,34 +56,37 @@ extern "C" {
 #define NG_PKTBUF_SIZE  (6144)
 #endif  /* NG_PKTBUF_SIZE */
 
+/**
+ * @brief   Initializes packet buffer module.
+ */
+void ng_pktbuf_init(void);
+
 /**
  * @brief   Adds a new ng_pktsnip_t and its packet to the packet buffer.
  *
- * @details This function is very powerful and reflects the unique characterics
- *          of ng_pktsnip_t of being reversed for either the sending or
- *          receiving context. Because of this the assumtion of the transmission
- *          direction, the state of the packet buffer and the values for the
- *          members of the resulting ng_pktsnip_t can be very different after
- *          execution of this function depending on what parameters you use:
- *
- * * The return value of this function is a @ref ng_pktsnip_t struct referred
- *   to as `result`
- * * for most cases the build-up of `result` will be pretty straight forward: Its
- *   members will be exactly as the given parameters (ng_pktsnip_t::next of
- *   result will be set to @p pkt). If @p pkt is not NULL it and in turn `result`
- *   are assumed to be in sending direction. For packet creation (@p pkt == NULL)
- *   no assumtions about direction of `result` will be made (since its
- *   ng_pktsnip::next will be set to NULL).
- * * if @p pkt != NULL, @p data = `pkt->data`, @p size < `pkt->size` receiving
- *   direction is assumed and the following values will be set:
- *   * ng_pktsnip_t::next of `result` = `pkt->next`
- *   * ng_pktsnip_t::data of `result` = @p data
- *   * ng_pktsnip_t::size of `result` = @p size
- *   * ng_pktsnip_t::next of @p pkt = `result`
- *   * ng_pktsnip_t::data of @p pkt = @p data + @p size
- *   * ng_pktsnip_t::size of @p pkt = old size value - @p size
- *
- *  graphically this can be represented as follows:
+ * @warning **Do not** change the fields of the ng_pktsnip_t created by this
+ *          function externally. This will most likely create memory leaks or
+ *          not allowed memory access.
+ *
+ * @param[in] next      Next ng_pktsnip_t in the packet. Leave NULL if you
+ *                      want to create a new packet.
+ * @param[in] data      Data of the new ng_pktsnip_t. If @p data is NULL no data
+ *                      will be inserted into `result`.
+ * @param[in] size      Length of @p data. May not be 0.
+ * @param[in] type      Protocol type of the ng_pktsnip_t.
+ *
+ * @return  Pointer to the packet part that represents the new ng_pktsnip_t.
+ * @return  NULL, if no space is left in the packet buffer.
+ * @return  NULL, if @p size == 0.
+ */
+ng_pktsnip_t *ng_pktbuf_add(ng_pktsnip_t *next, void *data, size_t size,
+                            ng_nettype_t type);
+
+/**
+ * @brief   Marks the first @p size bytes in a received packet with a new
+ *          packet snip that is appended to the packet.
+ *
+ *  Graphically this can be represented as follows:
  *  @code
  * Before                                    After
  * ======                                    =====
@@ -95,36 +98,23 @@ extern "C" {
  *  \__________pkt->size___________/          \_result->size_/ \__pkt->size__/
  *  @endcode
  *
- * @note    **Do not** change the ng_pktsnip_t::data and ng_pktsnip_t::size
- *          of a ng_pktsnip_t created by this function externally, except if
- *          they both are null or data is not from inside the packet buffer.
- *          This will most likely create memory leaks.
+ * @pre @p pkt != NULL && @p size != 0
  *
- * @param[in,out] pkt   The packet you want to add a ng_pktsnip_t to. Leave
- *                      NULL if you want to create a new packet. Members may
- *                      change values; see above.
- * @param[in] data      Data of the new ng_pktsnip_t. If @p data is NULL no data
- *                      will be inserted into `result`. If @p data is already
- *                      in the packet buffer (e.g. a payload of an already
- *                      allocated packet) it will not be duplicated.
- * @param[in] size      Length of @p data. If @p size is 0 no data will be inserted
- *                      into the the packet buffer and ng_pktsnip_t::data will be
- *                      set to @p data.
- * @param[in] type      Protocol type of the ng_pktsnip_t.
+ * @param[in] pkt   A received packet.
+ * @param[in] size  The size of the new packet snip.
+ * @param[in] type  The type of the new packet snip.
  *
- * @return  Pointer to the packet part that represents the new ng_pktsnip_t.
+ * @return  The new packet snip in @p pkt on success.
+ * @return  NULL, if pkt == NULL or size == 0 or size > pkt->size or pkt->data == NULL.
  * @return  NULL, if no space is left in the packet buffer.
- * @return  NULL, if @p pkt != NULL, @p data = `pkt->data`,
- *                and @p size > `pkt->data`.
  */
-ng_pktsnip_t *ng_pktbuf_add(ng_pktsnip_t *pkt, void *data, size_t size,
-                            ng_nettype_t type);
+ng_pktsnip_t *ng_pktbuf_mark(ng_pktsnip_t *pkt, size_t size, ng_nettype_t type);
 
 /**
  * @brief   Reallocates ng_pktsnip_t::data of @p pkt in the packet buffer, without
  *          changing the content.
  *
- * @pre `pkt->users == 1 && pkt->next == NULL` and @p pkt must be in packet buffer
+ * @pre ng_pktsnip_t::data of @p pkt is in the packet buffer.
  *
  * @details If enough memory is available behind it or @p size is smaller than
  *          the original size the packet then ng_pktsnip_t::data of @p pkt will
@@ -135,8 +125,6 @@ ng_pktsnip_t *ng_pktbuf_add(ng_pktsnip_t *pkt, void *data, size_t size,
  * @param[in] size  The size for @p pkt.
  *
  * @return  0, on success
- * @return  EINVAL, if precondition is not met
- * @return  ENOENT, if ng_pktsnip_t::data of @p pkt was not from the packet buffer.
  * @return  ENOMEM, if no space is left in the packet buffer or size was 0.
  */
 int ng_pktbuf_realloc_data(ng_pktsnip_t *pkt, size_t size);
@@ -182,7 +170,7 @@ ng_pktsnip_t *ng_pktbuf_start_write(ng_pktsnip_t *pkt);
  * @return  The new reference to @p pkt.
  */
 static inline ng_pktsnip_t *ng_pktbuf_remove_snip(ng_pktsnip_t *pkt,
-                                                  ng_pktsnip_t *snip)
+        ng_pktsnip_t *snip)
 {
     LL_DELETE(pkt, snip);
     snip->next = NULL;
@@ -213,9 +201,12 @@ void ng_pktbuf_stats(void);
 bool ng_pktbuf_is_empty(void);
 
 /**
- * @brief   Resets the whole packet buffer
+ * @brief   Checks if the implenation's internal invariants still uphold
+ *
+ * @return  true, the packet buffer is sane.
+ * @return  false, the packet buffer is insane.
  */
-void ng_pktbuf_reset(void);
+bool ng_pktbuf_is_sane(void);
 #endif
 
 #ifdef __cplusplus