source: trunk/kernel/mm/kcm.h

Last change on this file was 683, checked in by alain, 16 months ago

All modifications required to support the <tcp_chat> application
including error recovery in case of packet loss.A

File size: 8.5 KB
Line 
1/*
2 * kcm.h - Kernel Cache Manager definition.
3 *
4 * Authors    Alain Greiner (2016,2017,2018,2019,2020)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _KCM_H_
25#define _KCM_H_
26
27#include <list.h>
28#include <hal_kernel_types.h>
29#include <busylock.h>
30#include <page.h>
31#include <bits.h>
32#include <kmem.h>
33
34/****************************************************************************************
35 * This structure defines a generic Kernel Cache Manager, a fixed size block allocator.
36 * It returns an aligned block whose size is a power of 2, not smaller than a cache line,
37 * but smaller than a small PPM page. It exists in each cluster a specific KCM allocator
38 * for each possible block size. When the cache line contains 64 bytes and the page
39 * contains 4K bytes, the possible block sizes are 64, 128, 256, 512, 1024, 2048 bytes.
40 * These KCM allocators are initialized by the cluster_init() function.
41 *
42 * Each KCM cache is implemented as a set of "kcm_pages": a "kcm_page" is an aligned
43 * buffer in physical memory (allocated by the PPM allocator) such as :
44 *       buffer_size = block_size * 64  <=>  buffer_order = block_order + 6.
45 *
46 * A kcm_page contains always 64 kcm_blocks, but the first block (that cannot be smaller
47 * than 64 bytes) is used to store the kcm_page descriptor defining the page allocation
48 * status, and cannot be allocated to store data.
49 *
50 * A KCM cache is extensible, as new kcm_pages are dynamically allocated from the PPM
51 * allocator when required. For a given KCM cache the set of kcm_pages is split in two
52 * lists: the list of "full" pages (containing 63 allocated blocks), and the list of
53 * "active" pages (containing at least one free block). An "empty" page (containing
54 * only free blocks) is considered active, and is not released to PPM.
55 *
56 * To allow any thread running in any cluster to directly access the KCM of any cluster,
57 * ALMOS-MKH defines two sets of access functions, for local or remote access.
58 ***************************************************************************************/
59
60typedef struct kcm_s
61{
62        remote_busylock_t    lock;             /*! protect KCM allocator                   */
63
64        list_entry_t         full_root;        /*! root of full pages list                 */
65        list_entry_t         active_root;      /*! root of active pages list               */
66
67        uint32_t             full_pages_nr;    /*! number of full pages                    */
68        uint32_t             active_pages_nr;  /*! number of active pages                  */
69
70        uint32_t             order;            /*! ln( block_size )                        */
71}
72kcm_t;
73
74
75/****************************************************************************************
76 * This structure defines a KCM-page descriptor.
77 * A KCM-page contains (CONFIG_PPM_PAGE_SIZE / block_size) slots.
78 * Each slot contains one block, but the kcm page descriptor is stored in first slot.
79 * The current allocation status is defined by the 64 bits "status" bit vector: each
80 * non zero bit defines an allocated block / "count" is the number of allocated blocks.
81 * Each kcm_page is registered in one of the two following lists, rooted in the kcm:
82 * - full   : when count == max
83 * - active : count < max
84 ***************************************************************************************/
85
86typedef struct kcm_page_s
87{
88        uint64_t            status;            /*! bit vector: non-zero == allocated       */
89        uint32_t            count;             /*! number of allocated blocks in page      */
90        list_entry_t        list;              /*! [active / busy / free] list member      */
91        kcm_t             * kcm;               /*! pointer on kcm allocator                */
92        page_t            * page;              /*! pointer on physical page descriptor     */
93}
94kcm_page_t;
95
96/****************************************************************************************
97 * This function must be called by a local thread.
98 * It initializes a Kernel Cache Manager, depending on block size.
99 ****************************************************************************************
100 * @ kcm      : pointer on KCM to be initialized.
101 * @ order    : ln(block_size).
102 ***************************************************************************************/
103void kcm_init( kcm_t    * kcm,
104               uint32_t   order );
105
106/****************************************************************************************
107 * This function must be called by a local thread.
108 * It releases all memory allocated to a Kernel Cache Manager.
109 ****************************************************************************************
110 * @ kcm      : pointer on KCM manager to destroy.
111 ***************************************************************************************/
112void kcm_destroy( kcm_t  * kcm );
113
114/****************************************************************************************
115 * This function must be called by a local thread.
116 * It allocates one block from the local Kernel Cache Manager.
117 ****************************************************************************************
118 * @ order     :  ln( block-size ) == KCM allocator identifier.
119 * @ return pointer on allocated block if success / return NULL if failure
120 ***************************************************************************************/
121void * kcm_alloc( uint32_t order );
122
123/****************************************************************************************
124 * This function must be called by a local thread.
125 * It releases a previouly allocated block to the local Kernel Cache Manager.
126 ****************************************************************************************
127 * @ block_ptr   : local pointer on the released block.
128 * @ order       : log2( block_size in bytes ).
129 ***************************************************************************************/
130void kcm_free( void    * block_ptr,
131               uint32_t  order );
132
133
134
135
136/****************************************************************************************
137 * This function can be called by any thread running in any cluster.
138 * It allocates one fixed size block from a remote Kernel Cache Manager.
139 ****************************************************************************************
140 * @ kcm_cxy   : remote KCM cluster identifier.
141 * @ order     :  ln( block-size ) == KCM allocator identifier.
142 * @ return a local pointer on allocated block if success / return NULL if failure
143 ***************************************************************************************/
144void * kcm_remote_alloc( cxy_t    kcm_cxy,
145                         uint32_t order );
146
147/****************************************************************************************
148 * This function can be called by any thread running in any cluster.
149 * It releases a previouly allocated block to a remote Kernel Cache Manager.
150 ****************************************************************************************
151 * @ kcm_cxy     : remote KCM cluster identifier.
152 * @ block_ptr   : local pointer on the released buffer in remote cluster.
153 * @ order       : log2( block_size in bytes ).
154 ***************************************************************************************/
155void kcm_remote_free( cxy_t     kcm_cxy,
156                      void    * block_ptr,
157                      uint32_t  order );
158
159/****************************************************************************************
160 * This debug function can be called by any thread running in any cluster. It displays
161 * on TXT0 the state of a KCM, identified by the <kcm_cxy> & <kcm_ptr> arguments.
162 ****************************************************************************************
163 * @ kcm_cxy : remote KCM cluster identifier.
164 * @ kcm_ptr : local pointer on remote KCM.
165 ***************************************************************************************/
166void kcm_remote_display( cxy_t   kcm_cxy,
167                         kcm_t * kcm_ptr );
168
169#endif  /* _KCM_H_ */
Note: See TracBrowser for help on using the repository browser.