doc: add cryptodev sample code
[dpdk.git] / doc / guides / sample_app_ug / timer.rst
1 ..  BSD LICENSE
2     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
3     All rights reserved.
4
5     Redistribution and use in source and binary forms, with or without
6     modification, are permitted provided that the following conditions
7     are met:
8
9     * Redistributions of source code must retain the above copyright
10     notice, this list of conditions and the following disclaimer.
11     * Redistributions in binary form must reproduce the above copyright
12     notice, this list of conditions and the following disclaimer in
13     the documentation and/or other materials provided with the
14     distribution.
15     * Neither the name of Intel Corporation nor the names of its
16     contributors may be used to endorse or promote products derived
17     from this software without specific prior written permission.
18
19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31 Timer Sample Application
32 ========================
33
34 The Timer sample application is a simple application that demonstrates the use of a timer in a DPDK application.
35 This application prints some messages from different lcores regularly, demonstrating the use of timers.
36
37 Compiling the Application
38 -------------------------
39
40 #.  Go to the example directory:
41
42     .. code-block:: console
43
44         export RTE_SDK=/path/to/rte_sdk
45         cd ${RTE_SDK}/examples/timer
46
47 #.  Set the target (a default target is used if not specified). For example:
48
49     .. code-block:: console
50
51         export RTE_TARGET=x86_64-native-linuxapp-gcc
52
53     See the *DPDK Getting Started Guide* for possible *RTE_TARGET* values.
54
55 #.  Build the application:
56
57     .. code-block:: console
58
59         make
60
61 Running the Application
62 -----------------------
63
64 To run the example in linuxapp environment:
65
66 .. code-block:: console
67
68     $ ./build/timer -l 0-3 -n 4
69
70 Refer to the *DPDK Getting Started Guide* for general information on running applications and
71 the Environment Abstraction Layer (EAL) options.
72
73 Explanation
74 -----------
75
76 The following sections provide some explanation of the code.
77
78 Initialization and Main Loop
79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80
81 In addition to EAL initialization, the timer subsystem must be initialized, by calling the rte_timer_subsystem_init() function.
82
83 .. code-block:: c
84
85     /* init EAL */
86
87     ret = rte_eal_init(argc, argv);
88     if (ret < 0)
89         rte_panic("Cannot init EAL\n");
90
91     /* init RTE timer library */
92
93     rte_timer_subsystem_init();
94
95 After timer creation (see the next paragraph),
96 the main loop is executed on each slave lcore using the well-known rte_eal_remote_launch() and also on the master.
97
98 .. code-block:: c
99
100     /* call lcore_mainloop() on every slave lcore  */
101
102     RTE_LCORE_FOREACH_SLAVE(lcore_id) {
103         rte_eal_remote_launch(lcore_mainloop, NULL, lcore_id);
104     }
105
106     /* call it on master lcore too */
107
108     (void) lcore_mainloop(NULL);
109
110 The main loop is very simple in this example:
111
112 .. code-block:: c
113
114     while (1) {
115         /*
116          *   Call the timer handler on each core: as we don't
117          *   need a very precise timer, so only call
118          *   rte_timer_manage() every ~10ms (at 2 GHz). In a real
119          *   application, this will enhance performances as
120          *   reading the HPET timer is not efficient.
121         */
122
123         cur_tsc = rte_rdtsc();
124
125         diff_tsc = cur_tsc - prev_tsc;
126
127         if (diff_tsc > TIMER_RESOLUTION_CYCLES) {
128             rte_timer_manage();
129             prev_tsc = cur_tsc;
130         }
131     }
132
133 As explained in the comment, it is better to use the TSC register (as it is a per-lcore register) to check if the
134 rte_timer_manage() function must be called or not.
135 In this example, the resolution of the timer is 10 milliseconds.
136
137 Managing Timers
138 ~~~~~~~~~~~~~~~
139
140 In the main() function, the two timers are initialized.
141 This call to rte_timer_init() is necessary before doing any other operation on the timer structure.
142
143 .. code-block:: c
144
145     /* init timer structures */
146
147     rte_timer_init(&timer0);
148     rte_timer_init(&timer1);
149
150 Then, the two timers are configured:
151
152 *   The first timer (timer0) is loaded on the master lcore and expires every second.
153     Since the PERIODICAL flag is provided, the timer is reloaded automatically by the timer subsystem.
154     The callback function is timer0_cb().
155
156 *   The second timer (timer1) is loaded on the next available lcore every 333 ms.
157     The SINGLE flag means that the timer expires only once and must be reloaded manually if required.
158     The callback function is timer1_cb().
159
160 .. code-block:: c
161
162     /* load timer0, every second, on master lcore, reloaded automatically */
163
164     hz = rte_get_hpet_hz();
165
166     lcore_id = rte_lcore_id();
167
168     rte_timer_reset(&timer0, hz, PERIODICAL, lcore_id, timer0_cb, NULL);
169
170     /* load timer1, every second/3, on next lcore, reloaded manually */
171
172     lcore_id = rte_get_next_lcore(lcore_id, 0, 1);
173
174     rte_timer_reset(&timer1, hz/3, SINGLE, lcore_id, timer1_cb, NULL);
175
176 The callback for the first timer (timer0) only displays a message until a global counter reaches 20 (after 20 seconds).
177 In this case, the timer is stopped using the rte_timer_stop() function.
178
179 .. code-block:: c
180
181     /* timer0 callback */
182
183     static void
184     timer0_cb( attribute ((unused)) struct rte_timer *tim, __attribute ((unused)) void *arg)
185     {
186         static unsigned counter = 0;
187
188         unsigned lcore_id = rte_lcore_id();
189
190         printf("%s() on lcore %u\n", FUNCTION , lcore_id);
191
192         /* this timer is automatically reloaded until we decide to stop it, when counter reaches 20. */
193
194         if ((counter ++) == 20)
195             rte_timer_stop(tim);
196     }
197
198 The callback for the second timer (timer1) displays a message and reloads the timer on the next lcore, using the
199 rte_timer_reset() function:
200
201 .. code-block:: c
202
203     /* timer1 callback */
204
205     static void
206     timer1_cb( attribute ((unused)) struct rte_timer *tim, _attribute ((unused)) void *arg)
207     {
208         unsigned lcore_id = rte_lcore_id();
209         uint64_t hz;
210
211         printf("%s() on lcore %u\\n", FUNCTION , lcore_id);
212
213         /* reload it on another lcore */
214
215         hz = rte_get_hpet_hz();
216
217         lcore_id = rte_get_next_lcore(lcore_id, 0, 1);
218
219         rte_timer_reset(&timer1, hz/3, SINGLE, lcore_id, timer1_cb, NULL);
220     }