]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | /* SPDX-License-Identifier: BSD-3-Clause |
2 | * Copyright(c) 2017 Intel Corporation | |
3 | */ | |
4 | ||
5 | #ifndef _RTE_SERVICE_PRIVATE_H_ | |
6 | #define _RTE_SERVICE_PRIVATE_H_ | |
7 | ||
8 | /* This file specifies the internal service specification. | |
9 | * Include this file if you are writing a component that requires CPU cycles to | |
10 | * operate, and you wish to run the component using service cores | |
11 | */ | |
12 | #include <rte_compat.h> | |
13 | #include <rte_service.h> | |
14 | ||
15 | /** | |
16 | * Signature of callback function to run a service. | |
17 | */ | |
18 | typedef int32_t (*rte_service_func)(void *args); | |
19 | ||
20 | /** | |
21 | * The specification of a service. | |
22 | * | |
23 | * This struct contains metadata about the service itself, the callback | |
24 | * function to run one iteration of the service, a userdata pointer, flags etc. | |
25 | */ | |
26 | struct rte_service_spec { | |
27 | /** The name of the service. This should be used by the application to | |
28 | * understand what purpose this service provides. | |
29 | */ | |
30 | char name[RTE_SERVICE_NAME_MAX]; | |
31 | /** The callback to invoke to run one iteration of the service. */ | |
32 | rte_service_func callback; | |
33 | /** The userdata pointer provided to the service callback. */ | |
34 | void *callback_userdata; | |
35 | /** Flags to indicate the capabilities of this service. See defines in | |
36 | * the public header file for values of RTE_SERVICE_CAP_* | |
37 | */ | |
38 | uint32_t capabilities; | |
39 | /** NUMA socket ID that this service is affinitized to */ | |
40 | int socket_id; | |
41 | }; | |
42 | ||
43 | /** | |
44 | * Register a new service. | |
45 | * | |
46 | * A service represents a component that the requires CPU time periodically to | |
47 | * achieve its purpose. | |
48 | * | |
49 | * For example the eventdev SW PMD requires CPU cycles to perform its | |
50 | * scheduling. This can be achieved by registering it as a service, and the | |
51 | * application can then assign CPU resources to that service. | |
52 | * | |
53 | * Note that when a service component registers itself, it is not permitted to | |
54 | * add or remove service-core threads, or modify lcore-to-service mappings. The | |
55 | * only API that may be called by the service-component is | |
56 | * *rte_service_component_runstate_set*, which indicates that the service | |
57 | * component is ready to be executed. | |
58 | * | |
59 | * @param spec The specification of the service to register | |
60 | * @param[out] service_id A pointer to a uint32_t, which will be filled in | |
61 | * during registration of the service. It is set to the integers | |
62 | * service number given to the service. This parameter may be NULL. | |
63 | * @retval 0 Successfully registered the service. | |
64 | * -EINVAL Attempted to register an invalid service (eg, no callback | |
65 | * set) | |
66 | */ | |
67 | int32_t rte_service_component_register(const struct rte_service_spec *spec, | |
68 | uint32_t *service_id); | |
69 | ||
70 | /** | |
71 | * Unregister a service component. | |
72 | * | |
73 | * The service being removed must be stopped before calling this function. | |
74 | * | |
75 | * @retval 0 The service was successfully unregistered. | |
76 | * @retval -EBUSY The service is currently running, stop the service before | |
77 | * calling unregister. No action has been taken. | |
78 | */ | |
79 | int32_t rte_service_component_unregister(uint32_t id); | |
80 | ||
81 | /** | |
82 | * Private function to allow EAL to initialized default mappings. | |
83 | * | |
84 | * This function iterates all the services, and maps then to the available | |
85 | * cores. Based on the capabilities of the services, they are set to run on the | |
86 | * available cores in a round-robin manner. | |
87 | * | |
88 | * @retval 0 Success | |
89 | * @retval -ENOTSUP No service lcores in use | |
90 | * @retval -EINVAL Error while iterating over services | |
91 | * @retval -ENODEV Error in enabling service lcore on a service | |
92 | * @retval -ENOEXEC Error when starting services | |
93 | */ | |
94 | int32_t rte_service_start_with_defaults(void); | |
95 | ||
96 | /** | |
97 | * Set the backend runstate of a component. | |
98 | * | |
99 | * This function allows services to be registered at startup, but not yet | |
100 | * enabled to run by default. When the service has been configured (via the | |
101 | * usual method; eg rte_eventdev_configure, the service can mark itself as | |
102 | * ready to run. The differentiation between backend runstate and | |
103 | * service_runstate is that the backend runstate is set by the service | |
104 | * component while the service runstate is reserved for application usage. | |
105 | * | |
106 | * @retval 0 Success | |
107 | */ | |
108 | int32_t rte_service_component_runstate_set(uint32_t id, uint32_t runstate); | |
109 | ||
110 | /** | |
111 | * Initialize the service library. | |
112 | * | |
113 | * In order to use the service library, it must be initialized. EAL initializes | |
114 | * the library at startup. | |
115 | * | |
116 | * @retval 0 Success | |
117 | * @retval -EALREADY Service library is already initialized | |
118 | */ | |
119 | int32_t rte_service_init(void); | |
120 | ||
121 | /** | |
122 | * @internal Free up the memory that has been initialized. | |
123 | * This routine is to be invoked prior to process termination. | |
124 | * | |
125 | * @retval None | |
126 | */ | |
127 | void rte_service_finalize(void); | |
128 | ||
129 | #endif /* _RTE_SERVICE_PRIVATE_H_ */ |