1/***********************license start***************
2 * Copyright (c) 2003-2010  Cavium Inc. (support@cavium.com). All rights
3 * reserved.
4 *
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are
8 * met:
9 *
10 *   * Redistributions of source code must retain the above copyright
11 *     notice, this list of conditions and the following disclaimer.
12 *
13 *   * Redistributions in binary form must reproduce the above
14 *     copyright notice, this list of conditions and the following
15 *     disclaimer in the documentation and/or other materials provided
16 *     with the distribution.
17
18 *   * Neither the name of Cavium Inc. nor the names of
19 *     its contributors may be used to endorse or promote products
20 *     derived from this software without specific prior written
21 *     permission.
22
23 * This Software, including technical data, may be subject to U.S. export  control
24 * laws, including the U.S. Export Administration Act and its  associated
25 * regulations, and may be subject to export or import  regulations in other
26 * countries.
27
28 * TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
29 * AND WITH ALL FAULTS AND CAVIUM INC. MAKES NO PROMISES, REPRESENTATIONS OR
30 * WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH RESPECT TO
31 * THE SOFTWARE, INCLUDING ITS CONDITION, ITS CONFORMITY TO ANY REPRESENTATION OR
32 * DESCRIPTION, OR THE EXISTENCE OF ANY LATENT OR PATENT DEFECTS, AND CAVIUM
33 * SPECIFICALLY DISCLAIMS ALL IMPLIED (IF ANY) WARRANTIES OF TITLE,
34 * MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, LACK OF
35 * VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET POSSESSION OR
36 * CORRESPONDENCE TO DESCRIPTION. THE ENTIRE  RISK ARISING OUT OF USE OR
37 * PERFORMANCE OF THE SOFTWARE LIES WITH YOU.
38 ***********************license end**************************************/
39
40
41
42
43
44
45
46/**
47 * @file
48 *
49 * Interface to the hardware work queue timers.
50 *
51`* <hr>$Revision: 70030 $<hr>
52 */
53
54#ifndef __CVMX_TIM_H__
55#define __CVMX_TIM_H__
56
57#include "cvmx-clock.h"
58#include "cvmx-fpa.h"
59#include "cvmx-wqe.h"
60
61#include "executive-config.h"
62#ifdef CVMX_ENABLE_TIMER_FUNCTIONS
63#include "cvmx-config.h"
64#endif
65
66#ifdef	__cplusplus
67extern "C" {
68#endif
69
70#define CVMX_TIM_NUM_TIMERS   (OCTEON_IS_MODEL(OCTEON_CN68XX) ? 64 : 16)
71#define CVMX_TIM_NUM_BUCKETS  2048
72
73typedef enum
74{
75    CVMX_TIM_STATUS_SUCCESS = 0,
76    CVMX_TIM_STATUS_NO_MEMORY = -1,
77    CVMX_TIM_STATUS_TOO_FAR_AWAY = -2,
78    CVMX_TIM_STATUS_BUSY = -3
79} cvmx_tim_status_t;
80
81/**
82 * Each timer bucket contains a list of work queue entries to
83 * schedule when the timer fires. The list is implemented as
84 * a linked list of blocks. Each block contains an array of
85 * work queue entries followed by a next block pointer. Since
86 * these blocks are dynamically allocated off of a hardware
87 * memory pool, there actual size isn't known compile time.
88 * The next block pointer is stored in the last 8 bytes of
89 * the memory block.
90 */
91typedef struct cvmx_tim_entry_chunk
92{
93    volatile uint64_t entries[0];
94} cvmx_tim_entry_chunk_t;
95
96/**
97 * Each timer contains an array of buckets. Each bucket
98 * represents the list of work queue entries that should be
99 * scheduled when the timer fires.  The first 3 entries are used
100 * byt the hardware.
101 */
102typedef struct
103{
104   volatile uint64_t                first_chunk_addr;
105   volatile uint32_t                num_entries;    /**< Zeroed by HW after traversing list */
106   volatile uint32_t                chunk_remainder;/**< Zeroed by HW after traversing list */
107
108   // the remaining 16 bytes are not touched by hardware
109   volatile cvmx_tim_entry_chunk_t *last_chunk;
110   uint64_t                         pad;
111} cvmx_tim_bucket_entry_t;
112
113/**
114 * Structure representing an individual timer. Each timer has
115 * a timer period, a memory management pool, and a list of
116 * buckets.
117 */
118typedef struct
119{
120    cvmx_tim_bucket_entry_t*bucket;             /**< The timer buckets. Array of [CVMX_TIM_NUM_TIMERS][CVMX_TIM_NUM_BUCKETS] */
121    uint64_t                tick_cycles;        /**< How long a bucket represents */
122    uint64_t                start_time;         /**< Time the timer started in cycles */
123    uint32_t                bucket_shift;       /**< How long a bucket represents in ms */
124    uint32_t                num_buckets;        /**< How many buckets per wheel */
125    uint32_t                max_ticks;          /**< maximum number of ticks allowed for timer */
126} cvmx_tim_t;
127
128/**
129 * Structure used to store state information needed to delete
130 * an already scheduled timer entry. An instance of this
131 * structure must be passed to cvmx_tim_add_entry in order
132 * to be able to delete an entry later with
133 * cvmx_tim_delete_entry.
134 *
135 * NOTE: This structure should be considered opaque by the application,
136 * and the application should not access its members
137 */
138typedef struct
139{
140    uint64_t        commit_cycles;  /**< After this time the timer can't be changed */
141    uint64_t *      timer_entry_ptr;/**< Where the work entry is. Zero this
142                                            location to delete the entry */
143} cvmx_tim_delete_t;
144
145/**
146 * Global structure holding the state of all timers.
147 */
148extern cvmx_tim_t cvmx_tim;
149
150
151
152
153#ifdef CVMX_ENABLE_TIMER_FUNCTIONS
154/**
155 * Setup a timer for use. Must be called before the timer
156 * can be used.
157 *
158 * @param tick      Time between each bucket in microseconds. This must not be
159 *                  smaller than 1024/(clock frequency in MHz).
160 * @param max_ticks The maximum number of ticks the timer must be able
161 *                  to schedule in the future. There are guaranteed to be enough
162 *                  timer buckets such that:
163 *                  number of buckets >= max_ticks.
164 * @return Zero on success. Negative on error. Failures are possible
165 *         if the number of buckets needed is too large or memory
166 *         allocation fails for creating the buckets.
167 */
168int cvmx_tim_setup(uint64_t tick, uint64_t max_ticks);
169#endif
170
171/**
172 * Start the hardware timer processing
173 */
174extern void cvmx_tim_start(void);
175
176
177/**
178 * Stop the hardware timer processing. Timers stay configured.
179 */
180extern void cvmx_tim_stop(void);
181
182
183/**
184 * Stop the timer. After this the timer must be setup again
185 * before use.
186 */
187#ifdef CVMX_ENABLE_TIMER_FUNCTIONS
188extern void cvmx_tim_shutdown(void);
189#endif
190
191#ifdef CVMX_ENABLE_TIMER_FUNCTIONS
192/**
193 * Add a work queue entry to the timer.
194 *
195 * @param work_entry Work queue entry to add.
196 * @param ticks_from_now
197 * @param delete_info
198 *                   Optional pointer where to store information needed to
199 *                   delete the timer entry. If non NULL information needed
200 *                   to delete the timer entry before it fires is stored here.
201 *                   If you don't need to be able to delete the timer, pass
202 *                   NULL.
203 * @return Result return code
204 */
205static inline cvmx_tim_status_t cvmx_tim_add_entry(cvmx_wqe_t *work_entry, uint64_t ticks_from_now, cvmx_tim_delete_t *delete_info)
206{
207    cvmx_tim_bucket_entry_t*    work_bucket_ptr;
208    uint64_t                    work_bucket;
209    volatile uint64_t         * tim_entry_ptr;  /* pointer to wqe address in timer chunk */
210    uint64_t                    entries_per_chunk;
211
212    const uint64_t  cycles  = cvmx_clock_get_count(CVMX_CLOCK_TIM); /* Get our reference time early for accuracy */
213    const uint64_t  core_num    = cvmx_get_core_num();  /* One timer per processor, so use this to select */
214
215    /* Make sure the specified time won't wrap our bucket list */
216    if (ticks_from_now > cvmx_tim.max_ticks)
217    {
218        cvmx_dprintf("cvmx_tim_add_entry: Tried to schedule work too far away.\n");
219        return CVMX_TIM_STATUS_TOO_FAR_AWAY;
220    }
221
222    /* Since we have no way to synchronize, we can't update a timer that is
223        being used by the hardware. Two buckets forward should be safe */
224    if (ticks_from_now < 2)
225    {
226        cvmx_dprintf("cvmx_tim_add_entry: Tried to schedule work too soon. Delaying it.\n");
227        ticks_from_now = 2;
228    }
229
230    /* Get the bucket this work queue entry should be in. Remember the bucket
231        array is circular */
232    work_bucket = (((ticks_from_now * cvmx_tim.tick_cycles) + cycles - cvmx_tim.start_time)
233		   >> cvmx_tim.bucket_shift);
234
235    work_bucket_ptr = cvmx_tim.bucket + core_num * cvmx_tim.num_buckets + (work_bucket & (cvmx_tim.num_buckets - 1));
236    entries_per_chunk = (CVMX_FPA_TIMER_POOL_SIZE/8 - 1);
237
238    /* Check if we have room to add this entry into the existing list */
239    if (work_bucket_ptr->chunk_remainder)
240    {
241        /* Adding the work entry to the end of the existing list */
242        tim_entry_ptr = &(work_bucket_ptr->last_chunk->entries[entries_per_chunk - work_bucket_ptr->chunk_remainder]);
243        *tim_entry_ptr = cvmx_ptr_to_phys(work_entry);
244        work_bucket_ptr->chunk_remainder--;
245        work_bucket_ptr->num_entries++;
246    }
247    else
248    {
249        /* Current list is either completely empty or completely full. We need
250            to allocate a new chunk for storing this work entry */
251        cvmx_tim_entry_chunk_t *new_chunk = (cvmx_tim_entry_chunk_t *)cvmx_fpa_alloc(CVMX_FPA_TIMER_POOL);
252        if (new_chunk == NULL)
253        {
254            cvmx_dprintf("cvmx_tim_add_entry: Failed to allocate memory for new chunk.\n");
255            return CVMX_TIM_STATUS_NO_MEMORY;
256        }
257
258        /* Does a chunk currently exist? We have to check num_entries since
259            the hardware doesn't NULL out the chunk pointers on free */
260        if (work_bucket_ptr->num_entries)
261        {
262            /* This chunk must be appended to an existing list by putting
263            ** its address in the last spot of the existing chunk. */
264            work_bucket_ptr->last_chunk->entries[entries_per_chunk] = cvmx_ptr_to_phys(new_chunk);
265            work_bucket_ptr->num_entries++;
266        }
267        else
268        {
269            /* This is the very first chunk. Add it */
270            work_bucket_ptr->first_chunk_addr = cvmx_ptr_to_phys(new_chunk);
271            work_bucket_ptr->num_entries = 1;
272        }
273        work_bucket_ptr->last_chunk = new_chunk;
274        work_bucket_ptr->chunk_remainder = entries_per_chunk - 1;
275        tim_entry_ptr = &(new_chunk->entries[0]);
276        *tim_entry_ptr = cvmx_ptr_to_phys(work_entry);
277    }
278
279    /* If the user supplied a delete info structure then fill it in */
280    if (delete_info)
281    {
282        /* It would be very bad to delete a timer entry after, or during the
283            timer's processing. During the processing could yield unpredicatable
284            results, but after would always be bad. Modifying the entry after
285            processing means we would be changing data in a buffer that has been
286            freed, and possible allocated again. For this reason we store a
287            commit cycle count in the delete structure. If we are after this
288            count we will refuse to delete the timer entry. */
289        delete_info->commit_cycles = cycles + (ticks_from_now - 2) * cvmx_tim.tick_cycles;
290        delete_info->timer_entry_ptr = (uint64_t *)tim_entry_ptr;  /* Cast to non-volatile type */
291    }
292
293    CVMX_SYNCWS; /* Make sure the hardware timer unit can access valid data from L2 */
294
295    return CVMX_TIM_STATUS_SUCCESS;
296}
297#endif
298
299
300/**
301 * Delete a timer entry scheduled using cvmx_tim_add_entry.
302 * Deleting a timer will fail if it has already triggered or
303 * might be in progress. The actual state of the work queue
304 * entry isn't changed. You need to dispose of it properly.
305 *
306 * @param delete_info
307 *               Structure passed to cvmx_tim_add_entry to store the
308 *               information needed to delete a timer entry.
309 * @return CVMX_TIM_STATUS_BUSY if the timer was not deleted, otherwise
310 *         CVMX_TIM_STATUS_SUCCESS.
311 */
312static inline cvmx_tim_status_t cvmx_tim_delete_entry(cvmx_tim_delete_t *delete_info)
313{
314    const uint64_t cycles = cvmx_clock_get_count(CVMX_CLOCK_TIM);
315
316    if ((int64_t)(cycles - delete_info->commit_cycles) < 0)
317    {
318        /* Timer is far enough away. Safe to delete */
319        *delete_info->timer_entry_ptr = 0;
320        return CVMX_TIM_STATUS_SUCCESS;
321    }
322    else
323    {
324        /* Timer is passed the commit time. It cannot be stopped */
325        return CVMX_TIM_STATUS_BUSY;
326    }
327}
328
329#ifdef	__cplusplus
330}
331#endif
332
333#endif // __CVMX_TIM_H__
334