[dpdk-dev] [RFC] replace master/slave with primary/secondary

[Stephen Hemminger <stephen@networkplumber.org>]

I have a full patch that replaces the master/slave lcore
naming (widely used in DPDK) with a better primary/secondary naming.

For now this is just a trial balloon to see what the impact would
look like. The change mostly automated so likely that things
are broken.

It is hard to break a change like this down, and still
keep git bisection clean.

It keeps rte_master_lcore_id and RTE_FOREACH_SLAVE as deprecated
items so that user code can still be built but they will be motivated
to change.

Here is a sample of what it would look like:

diff --git a/lib/librte_eal/include/rte_launch.h b/lib/librte_eal/include/rte_launch.h
index 06a671752ace..3d81207988a0 100644
--- a/lib/librte_eal/include/rte_launch.h
+++ b/lib/librte_eal/include/rte_launch.h
@@ -32,12 +32,12 @@ typedef int (lcore_function_t)(void *);
 /**
  * Launch a function on another lcore.
  *
- * To be executed on the MASTER lcore only.
+ * To be executed on the PRIMARY lcore only.
  *
- * Sends a message to a slave lcore (identified by the slave_id) that
+ * Sends a message to a secondary lcore (identified by the id) that
  * is in the WAIT state (this is true after the first call to
  * rte_eal_init()). This can be checked by first calling
- * rte_eal_wait_lcore(slave_id).
+ * rte_eal_wait_lcore(id).
  *
  * When the remote lcore receives the message, it switches to
  * the RUNNING state, then calls the function f with argument arg. Once the
@@ -45,7 +45,7 @@ typedef int (lcore_function_t)(void *);
  * the return value of f is stored in a local variable to be read using
  * rte_eal_wait_lcore().
  *
- * The MASTER lcore returns as soon as the message is sent and knows
+ * The PRIMARY lcore returns as soon as the message is sent and knows
  * nothing about the completion of f.
  *
  * Note: This function is not designed to offer optimum
@@ -56,37 +56,37 @@ typedef int (lcore_function_t)(void *);
  *   The function to be called.
  * @param arg
  *   The argument for the function.
- * @param slave_id
+ * @param id
  *   The identifier of the lcore on which the function should be executed.
  * @return
  *   - 0: Success. Execution of function f started on the remote lcore.
  *   - (-EBUSY): The remote lcore is not in a WAIT state.
  */
-int rte_eal_remote_launch(lcore_function_t *f, void *arg, unsigned slave_id);
+int rte_eal_remote_launch(lcore_function_t *f, void *arg, unsigned id);
 
 /**
- * This enum indicates whether the master core must execute the handler
+ * This enum indicates whether the primary core must execute the handler
  * launched on all logical cores.
  */
-enum rte_rmt_call_master_t {
-	SKIP_MASTER = 0, /**< lcore handler not executed by master core. */
-	CALL_MASTER,     /**< lcore handler executed by master core. */
+enum rte_rmt_call_primary_t {
+	SKIP_PRIMARY = 0, /**< lcore handler not executed by primary core. */
+	CALL_PRIMARY,     /**< lcore handler executed by primary core. */
 };
 
 /**
  * Launch a function on all lcores.
  *
- * Check that each SLAVE lcore is in a WAIT state, then call
+ * Check that each secondary lcore is in a WAIT state, then call
  * rte_eal_remote_launch() for each lcore.
  *
  * @param f
  *   The function to be called.
  * @param arg
  *   The argument for the function.
- * @param call_master
- *   If call_master set to SKIP_MASTER, the MASTER lcore does not call
- *   the function. If call_master is set to CALL_MASTER, the function
- *   is also called on master before returning. In any case, the master
+ * @param call_primary
+ *   If call_primary set to SKIP_PRIMARY, the PRIMARY lcore does not call
+ *   the function. If call_primary is set to CALL_PRIMARY, the function
+ *   is also called on primary before returning. In any case, the primary
  *   lcore returns as soon as it finished its job and knows nothing
  *   about the completion of f on the other lcores.
  * @return
@@ -95,49 +95,49 @@ enum rte_rmt_call_master_t {
  *     case, no message is sent to any of the lcores.
  */
 int rte_eal_mp_remote_launch(lcore_function_t *f, void *arg,
-			     enum rte_rmt_call_master_t call_master);
+			     enum rte_rmt_call_primary_t call_primary);
 
 /**
- * Get the state of the lcore identified by slave_id.
+ * Get the state of the lcore identified by id.
  *
- * To be executed on the MASTER lcore only.
+ * To be executed on the PRIMARY lcore only.
  *
- * @param slave_id
+ * @param id
  *   The identifier of the lcore.
  * @return
  *   The state of the lcore.
  */
-enum rte_lcore_state_t rte_eal_get_lcore_state(unsigned slave_id);
+enum rte_lcore_state_t rte_eal_get_lcore_state(unsigned id);
 
 /**
  * Wait until an lcore finishes its job.
  *
- * To be executed on the MASTER lcore only.
+ * To be executed on the PRIMARY lcore only.
  *
- * If the slave lcore identified by the slave_id is in a FINISHED state,
+ * If the lcore identified by the id is in a FINISHED state,
  * switch to the WAIT state. If the lcore is in RUNNING state, wait until
  * the lcore finishes its job and moves to the FINISHED state.
  *
- * @param slave_id
+ * @param id
  *   The identifier of the lcore.
  * @return
- *   - 0: If the lcore identified by the slave_id is in a WAIT state.
+ *   - 0: If the lcore identified by the id is in a WAIT state.
  *   - The value that was returned by the previous remote launch
- *     function call if the lcore identified by the slave_id was in a
+ *     function call if the lcore identified by the id was in a
  *     FINISHED or RUNNING state. In this case, it changes the state
  *     of the lcore to WAIT.
  */
-int rte_eal_wait_lcore(unsigned slave_id);
+int rte_eal_wait_lcore(unsigned id);
 
 /**
  * Wait until all lcores finish their jobs.
  *
- * To be executed on the MASTER lcore only. Issue an
+ * To be executed on the PRIMARY lcore only. Issue an
  * rte_eal_wait_lcore() for every lcore. The return values are
  * ignored.
  *
  * After a call to rte_eal_mp_wait_lcore(), the caller can assume
- * that all slave lcores are in a WAIT state.
+ * that all secondary lcores are in a WAIT state.
  */
 void rte_eal_mp_wait_lcore(void);
 
diff --git a/lib/librte_eal/include/rte_lcore.h b/lib/librte_eal/include/rte_lcore.h
index 339046bc8691..e43985db17df 100644
--- a/lib/librte_eal/include/rte_lcore.h
+++ b/lib/librte_eal/include/rte_lcore.h
@@ -54,13 +54,21 @@ rte_lcore_id(void)
 }
 
 /**
- * Get the id of the master lcore
+ * Get the id of the primary lcore
  *
  * @return
- *   the id of the master lcore
+ *   the id of the primary lcore
  */
-unsigned int rte_get_master_lcore(void);
+unsigned int rte_get_primary_lcore(void);
 
+/**
+ * Deprecated API to get the id of the primary lcore
+ *
+ * @return
+ *   the id of the primary lcore
+ */
+unsigned int rte_get_master_lcore(void) __rte_deprecated;	
+	
 /**
  * Return the number of execution units (lcores) on the system.
  *
@@ -179,15 +187,15 @@ int rte_lcore_is_enabled(unsigned int lcore_id);
  *
  * @param i
  *   The current lcore (reference).
- * @param skip_master
- *   If true, do not return the ID of the master lcore.
+ * @param skip_primary
+ *   If true, do not return the ID of the primary lcore.
  * @param wrap
  *   If true, go back to 0 when RTE_MAX_LCORE is reached; otherwise,
  *   return RTE_MAX_LCORE.
  * @return
  *   The next lcore_id or RTE_MAX_LCORE if not found.
  */
-unsigned int rte_get_next_lcore(unsigned int i, int skip_master, int wrap);
+unsigned int rte_get_next_lcore(unsigned int i, int skip_primary, int wrap);
 
 /**
  * Macro to browse all running lcores.
@@ -198,13 +206,21 @@ unsigned int rte_get_next_lcore(unsigned int i, int skip_master, int wrap);
 	     i = rte_get_next_lcore(i, 0, 0))
 
 /**
- * Macro to browse all running lcores except the master lcore.
+ * Macro to browse all running lcores except the primary lcore.
  */
-#define RTE_LCORE_FOREACH_SLAVE(i)					\
+#define RTE_LCORE_FOREACH_SECONDARY(i)					\
 	for (i = rte_get_next_lcore(-1, 1, 0);				\
 	     i<RTE_MAX_LCORE;						\
 	     i = rte_get_next_lcore(i, 1, 0))
 
+/**
+ * Backword compatiablity
+ */
+#define RTE_LCORE_FOREACH_SLAVE(x)					\
+	_Pragma("GCC warning \"'RTE_LCORE_FOREACH_SLAVE' macro is deprecated\"") \
+	RTE_LCORE_FOREACH_SECONDARY(x)
+
+
 /**
  * Set core affinity of the current thread.
  * Support both EAL and non-EAL thread and update TLS.
diff --git a/lib/librte_eal/linux/eal.c b/lib/librte_eal/linux/eal.c
index f162124a379c..969b6d5720f8 100644
--- a/lib/librte_eal/linux/eal.c
+++ b/lib/librte_eal/linux/eal.c
@@ -879,7 +879,7 @@ eal_check_mem_on_local_socket(void)
 {
 	int socket_id;
 
-	socket_id = rte_lcore_to_socket_id(rte_config.master_lcore);
+	socket_id = rte_lcore_to_socket_id(rte_config.primary_lcore);
 
 	if (rte_memseg_list_walk(check_socket, &socket_id) == 0)
 		RTE_LOG(WARNING, EAL, "WARNING: Master core has no memory on local socket!\n");
@@ -1205,23 +1205,23 @@ rte_eal_init(int argc, char **argv)
 
 	eal_check_mem_on_local_socket();
 
-	eal_thread_init_master(rte_config.master_lcore);
+	eal_thread_init_primary(rte_config.primary_lcore);
 
 	ret = eal_thread_dump_affinity(cpuset, sizeof(cpuset));
 
 	RTE_LOG(DEBUG, EAL, "Master lcore %u is ready (tid=%zx;cpuset=[%s%s])\n",
-		rte_config.master_lcore, (uintptr_t)thread_id, cpuset,
+		rte_config.primary_lcore, (uintptr_t)thread_id, cpuset,
 		ret == 0 ? "" : "...");
 
-	RTE_LCORE_FOREACH_SLAVE(i) {
+	RTE_LCORE_FOREACH_SECONDARY(i) {
 
 		/*
-		 * create communication pipes between master thread
+		 * create communication pipes between primary thread
 		 * and children
 		 */
-		if (pipe(lcore_config[i].pipe_master2slave) < 0)
+		if (pipe(lcore_config[i].pipe_primary2secondary) < 0)
 			rte_panic("Cannot create pipe\n");
-		if (pipe(lcore_config[i].pipe_slave2master) < 0)
+		if (pipe(lcore_config[i].pipe_secondary2primary) < 0)
 			rte_panic("Cannot create pipe\n");
 
 		lcore_config[i].state = WAIT;
@@ -1234,7 +1234,7 @@ rte_eal_init(int argc, char **argv)
 
 		/* Set thread_name for aid in debugging. */
 		snprintf(thread_name, sizeof(thread_name),
-			"lcore-slave-%d", i);
+			"lcore-secondary-%d", i);
 		ret = rte_thread_setname(lcore_config[i].thread_id,
 						thread_name);
 		if (ret != 0)