1 /*
2  * Copyright (c) 2015, Xilinx Inc. and Contributors. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 /*
8  * @file	sys.h
9  * @brief	System primitives for libmetal.
10  * @brief	Top level include internal to libmetal library code.
11  */
12 
13 #ifndef __METAL_SYS__H__
14 #define __METAL_SYS__H__
15 
16 #include <stdlib.h>
17 
18 #include <metal/log.h>
19 #include <metal/list.h>
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24 
25 /** \defgroup system Top Level Interfaces
26  *  @{ */
27 
28 /** Physical address type. */
29 typedef unsigned long metal_phys_addr_t;
30 
31 /** Interrupt request number. */
32 typedef int metal_irq_t;
33 
34 /** Bad offset into shared memory or I/O region. */
35 #define METAL_BAD_OFFSET	((unsigned long)-1)
36 
37 /** Bad physical address value. */
38 #define METAL_BAD_PHYS		((metal_phys_addr_t)-1)
39 
40 /** Bad virtual address value. */
41 #define METAL_BAD_VA		((void *)-1)
42 
43 /** Bad IRQ. */
44 #define METAL_BAD_IRQ		((metal_irq_t)-1)
45 
46 /**
47  * Initialization configuration for libmetal.
48  */
49 struct metal_init_params {
50 
51 	/** log message handler (defaults to stderr). */
52 	metal_log_handler		log_handler;
53 
54 	/** default log message level (defaults to emergency). */
55 	enum metal_log_level		log_level;
56 };
57 
58 /**
59  * System independent runtime state for libmetal.  This is part of a system
60  * specific singleton data structure (@see _metal).
61  */
62 struct metal_common_state {
63 	/** Current log level. */
64 	enum metal_log_level		log_level;
65 
66 	/** Current log handler (null for none). */
67 	metal_log_handler		log_handler;
68 
69 	/** List of registered buses. */
70 	struct metal_list		bus_list;
71 
72 	/** Generic statically defined shared memory segments. */
73 	struct metal_list		generic_shmem_list;
74 
75 	/** Generic statically defined devices. */
76 	struct metal_list		generic_device_list;
77 };
78 
79 struct metal_state;
80 
81 #include <metal/system/generic/sys.h>
82 
83 #ifndef METAL_INIT_DEFAULTS
84 #define METAL_INIT_DEFAULTS				\
85 {							\
86 	.log_handler	= metal_default_log_handler,	\
87 	.log_level	= METAL_LOG_INFO,		\
88 }
89 #endif
90 
91 /** System specific runtime data. */
92 extern struct metal_state _metal;
93 
94 /**
95  * @brief	Initialize libmetal.
96  *
97  * Initialize the libmetal library.
98  *
99  * @param[in]	params	Initialization params (@see metal_init_params).
100  *
101  * @return	0 on success, or -errno on failure.
102  *
103  * @see metal_finish
104  */
105 extern int metal_init(const struct metal_init_params *params);
106 
107 /**
108  * @brief	Shutdown libmetal.
109  *
110  * Shutdown the libmetal library, and release all reserved resources.
111  *
112  * @see metal_init
113  */
114 extern void metal_finish(void);
115 
116 #ifdef METAL_INTERNAL
117 
118 /**
119  * @brief	libmetal system initialization.
120  *
121  * This function initializes libmetal on Linux or Generic platforms.  This
122  * involves obtaining necessary pieces of system information (sysfs mount path,
123  * page size, etc.).
124  *
125  * @param[in]	params	Initialization parameters (@see metal_init_params).
126  * @return	0 on success, or -errno on failure.
127  */
128 extern int metal_sys_init(const struct metal_init_params *params);
129 
130 /**
131  * @brief	libmetal system shutdown.
132  *
133  * This function shuts down and releases resources held by libmetal Linux or
134  * Generic platform layers.
135  *
136  * @see metal_sys_init
137  */
138 extern void metal_sys_finish(void);
139 
140 #endif
141 
142 /** @} */
143 
144 #ifdef __cplusplus
145 }
146 #endif
147 
148 #endif /* __METAL_SYS__H__ */
149