doc: add Meson coding style to contributors guide

[dpdk.git] / lib / librte_rawdev / rte_rawdev_pmd.h

diff --git a/lib/librte_rawdev/rte_rawdev_pmd.h b/lib/librte_rawdev/rte_rawdev_pmd.h
index bb9bbc3..b1bed13 100644 (file)
--- a/lib/librte_rawdev/rte_rawdev_pmd.h
+++ b/lib/librte_rawdev/rte_rawdev_pmd.h
@@ -11,9 +11,6 @@
  * @note
  * Driver facing APIs for a raw device. These are not to be called directly by
  * any application.
- *
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
  */
 
 #ifdef __cplusplus
@@ -73,8 +70,6 @@ struct rte_rawdev_global {
        uint16_t nb_devs;
 };
 
-extern struct rte_rawdev_global *rte_rawdev_globals;
-/** Pointer to global raw devices data structure. */
 extern struct rte_rawdev *rte_rawdevs;
 /** The pool of rte_rawdev structures. */
 
@@ -143,12 +138,15 @@ rte_rawdev_pmd_is_valid_dev(uint8_t dev_id)
  *   Raw device pointer
  * @param dev_info
  *   Raw device information structure
+ * @param dev_private_size
+ *   The size of the structure pointed to by dev_info->dev_private
  *
  * @return
- *   Returns 0 on success
+ *   Returns 0 on success, negative error code on failure
  */
-typedef void (*rawdev_info_get_t)(struct rte_rawdev *dev,
-                                 rte_rawdev_obj_t dev_info);
+typedef int (*rawdev_info_get_t)(struct rte_rawdev *dev,
+                                 rte_rawdev_obj_t dev_info,
+                                 size_t dev_private_size);
 
 /**
  * Configure a device.
@@ -157,12 +155,15 @@ typedef void (*rawdev_info_get_t)(struct rte_rawdev *dev,
  *   Raw device pointer
  * @param config
  *   Void object containing device specific configuration
+ * @param config_size
+ *   Size of the memory allocated for the configuration
  *
  * @return
  *   Returns 0 on success
  */
 typedef int (*rawdev_configure_t)(const struct rte_rawdev *dev,
-                                 rte_rawdev_obj_t config);
+                                 rte_rawdev_obj_t config,
+                                 size_t config_size);
 
 /**
  * Start a configured device.
@@ -215,11 +216,16 @@ typedef int (*rawdev_reset_t)(struct rte_rawdev *dev);
  *   Raw device queue index
  * @param[out] queue_conf
  *   Raw device queue configuration structure
+ * @param queue_conf_size
+ *   Size of the memory allocated for the configuration
  *
+ * @return
+ *   Returns 0 on success, negative errno on failure
  */
-typedef void (*rawdev_queue_conf_get_t)(struct rte_rawdev *dev,
+typedef int (*rawdev_queue_conf_get_t)(struct rte_rawdev *dev,
                                        uint16_t queue_id,
-                                       rte_rawdev_obj_t queue_conf);
+                                       rte_rawdev_obj_t queue_conf,
+                                       size_t queue_conf_size);
 
 /**
  * Setup an raw queue.
@@ -230,13 +236,16 @@ typedef void (*rawdev_queue_conf_get_t)(struct rte_rawdev *dev,
  *   Rawqueue index
  * @param queue_conf
  *   Rawqueue configuration structure
+ * @param queue_conf_size
+ *   Size of the memory allocated for the configuration
  *
  * @return
  *   Returns 0 on success.
  */
 typedef int (*rawdev_queue_setup_t)(struct rte_rawdev *dev,
                                    uint16_t queue_id,
-                                   rte_rawdev_obj_t queue_conf);
+                                   rte_rawdev_obj_t queue_conf,
+                                   size_t queue_conf_size);
 
 /**
  * Release resources allocated by given raw queue.
@@ -260,7 +269,7 @@ typedef int (*rawdev_queue_release_t)(struct rte_rawdev *dev,
  * This function helps in getting queue count supported, independently. It
  * can help in cases where iterator needs to be implemented.
  *
- * @param
+ * @param dev
  *   Raw device pointer
  * @return
  *   Number of queues; 0 is assumed to be a valid response.
@@ -276,7 +285,7 @@ typedef uint16_t (*rawdev_queue_count_t)(struct rte_rawdev *dev);
  *
  * @param dev
  *   Raw device pointer
- * @param bufs
+ * @param buffers
  *   array of buffers
  * @param count
  *   number of buffers passed
@@ -284,7 +293,7 @@ typedef uint16_t (*rawdev_queue_count_t)(struct rte_rawdev *dev);
  *   an opaque object representing context of the call; for example, an
  *   application can pass information about the queues on which enqueue needs
  *   to be done. Or, the enqueue operation might be passed reference to an
- *   object containing a callback (agreed upon between applicatio and driver).
+ *   object containing a callback (agreed upon between application and driver).
  *
  * @return
  *   >=0 Count of buffers successfully enqueued (0: no buffers enqueued)
@@ -300,7 +309,7 @@ typedef int (*rawdev_enqueue_bufs_t)(struct rte_rawdev *dev,
  *
  * @param dev
  *   Raw device pointer
- * @param bufs
+ * @param buffers
  *   array of buffers
  * @param count
  *   Max buffers expected to be dequeued
@@ -441,7 +450,7 @@ typedef uint64_t (*rawdev_xstats_get_by_name_t)(const struct rte_rawdev *dev,
  *
  * @param dev
  *   Raw device pointer
- * @param status
+ * @param status_info
  *   void block containing device specific status information
  * @return
  *   0 for success,
@@ -465,12 +474,12 @@ typedef int (*rawdev_firmware_version_get_t)(struct rte_rawdev *dev,
                                             rte_rawdev_obj_t version_info);
 
 /**
- * Load firwmare from a buffer (DMA'able)
+ * Load firmware from a buffer (DMA'able)
  *
  * @param dev
  *   Raw device pointer
- * @param firmware_file
- *   file pointer to firmware area
+ * @param firmware_buf
+ *   Pointer to firmware image
  * @return
  *   >0, ~0: for successful load
  *   <0: for failure
@@ -482,7 +491,7 @@ typedef int (*rawdev_firmware_load_t)(struct rte_rawdev *dev,
                                      rte_rawdev_obj_t firmware_buf);
 
 /**
- * Unload firwmare
+ * Unload firmware
  *
  * @param dev
  *   Raw device pointer
@@ -501,7 +510,7 @@ typedef int (*rawdev_firmware_unload_t)(struct rte_rawdev *dev);
  * @return
  *   Return 0 on success
  */
-typedef int (*rawdev_selftest_t)(void);
+typedef int (*rawdev_selftest_t)(uint16_t dev_id);
 
 /** Rawdevice operations function pointer table */
 struct rte_rawdev_ops {
@@ -550,7 +559,7 @@ struct rte_rawdev_ops {
        /**< Reset the statistics values in xstats. */
        rawdev_xstats_reset_t xstats_reset;
 
-       /**< Obtainer firmware status */
+       /**< Obtain firmware status */
        rawdev_firmware_status_get_t firmware_status_get;
        /**< Obtain firmware version information */
        rawdev_firmware_version_get_t firmware_version_get;
@@ -570,7 +579,9 @@ struct rte_rawdev_ops {
  * @param name
  *   Unique identifier name for each device
  * @param dev_private_size
- *   Private data allocated within rte_rawdev object.
+ *   Size of private data memory allocated within rte_rawdev object.
+ *   Set to 0 to disable internal memory allocation and allow for
+ *   self-allocation.
  * @param socket_id
  *   Socket to allocate resources on.
  * @return