1#- 2# Copyright (c) 2016 Landon Fuller <landon@landonf.org> 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# 1. Redistributions of source code must retain the above copyright 9# notice, this list of conditions and the following disclaimer. 10# 2. Redistributions in binary form must reproduce the above copyright 11# notice, this list of conditions and the following disclaimer in the 12# documentation and/or other materials provided with the distribution. 13# 14# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17# IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 18# INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 19# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 20# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 21# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 22# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 23# USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24# 25# $FreeBSD$ 26 27#include <sys/param.h> 28#include <sys/bus.h> 29 30#include <machine/bus.h> 31#include <sys/rman.h> 32#include <machine/resource.h> 33 34#include <dev/bhnd/bhnd.h> 35#include <dev/bhnd/bhnd_erom_types.h> 36 37INTERFACE bhnd_erom; 38 39# 40# bhnd(4) device enumeration. 41# 42# Provides a common parser interface to the incompatible device enumeration 43# tables used by bhnd(4) buses. 44# 45 46/** 47 * Probe to see if this device enumeration class supports the bhnd bus 48 * mapped by the given resource, returning a standard newbus device probe 49 * result (see BUS_PROBE_*) and the probed chip identification. 50 * 51 * @param cls The erom class to probe. 52 * @param res A resource mapping the first bus core. 53 * @param offset Offset to the first bus core within @p res. 54 * @param hint Hint used to identify the device. If chipset supports 55 * standard chip identification registers within the first 56 * core, this parameter should be NULL. 57 * @param[out] cid On success, the probed chip identifier. 58 * 59 * @retval 0 if this is the only possible device enumeration 60 * parser for the probed bus. 61 * @retval negative if the probe succeeds, a negative value should be 62 * returned; the parser returning the highest negative 63 * value will be selected to handle device enumeration. 64 * @retval ENXIO If the bhnd bus type is not handled by this parser. 65 * @retval positive if an error occurs during probing, a regular unix error 66 * code should be returned. 67 */ 68STATICMETHOD int probe { 69 bhnd_erom_class_t *cls; 70 struct bhnd_resource *res; 71 bus_size_t offset; 72 const struct bhnd_chipid *hint; 73 struct bhnd_chipid *cid; 74}; 75 76/** 77 * Probe to see if this device enumeration class supports the bhnd bus 78 * mapped at the given bus space tag and handle, returning a standard 79 * newbus device probe result (see BUS_PROBE_*) and the probed 80 * chip identification. 81 * 82 * @param cls The erom class to probe. 83 * @param bst Bus space tag. 84 * @param bsh Bus space handle mapping the first bus core. 85 * @param paddr The physical address of the core mapped by @p bst and 86 * @p bsh. 87 * @param hint Hint used to identify the device. If chipset supports 88 * standard chip identification registers within the first 89 * core, this parameter should be NULL. 90 * @param[out] cid On success, the probed chip identifier. 91 * 92 * @retval 0 if this is the only possible device enumeration 93 * parser for the probed bus. 94 * @retval negative if the probe succeeds, a negative value should be 95 * returned; the parser returning the highest negative 96 * value will be selected to handle device enumeration. 97 * @retval ENXIO If the bhnd bus type is not handled by this parser. 98 * @retval positive if an error occurs during probing, a regular unix error 99 * code should be returned. 100 */ 101STATICMETHOD int probe_static { 102 bhnd_erom_class_t *cls; 103 bus_space_tag_t bst; 104 bus_space_handle_t bsh; 105 bus_addr_t paddr; 106 const struct bhnd_chipid *hint; 107 struct bhnd_chipid *cid; 108}; 109 110/** 111 * Initialize a device enumeration table parser. 112 * 113 * @param erom The erom parser to initialize. 114 * @param cid The device's chip identifier. 115 * @param parent The parent device from which EROM resources should 116 * be allocated. 117 * @param rid The resource id to be used when allocating the 118 * enumeration table. 119 * 120 * @retval 0 success 121 * @retval non-zero if an error occurs initializing the EROM parser, 122 * a regular unix error code will be returned. 123 */ 124METHOD int init { 125 bhnd_erom_t *erom; 126 const struct bhnd_chipid *cid; 127 device_t parent; 128 int rid; 129}; 130 131/** 132 * Initialize an device enumeration table parser using the provided bus space 133 * tag and handle. 134 * 135 * @param erom The erom parser to initialize. 136 * @param cid The device's chip identifier. 137 * @param bst Bus space tag. 138 * @param bsh Bus space handle mapping the full bus enumeration 139 * space. 140 * 141 * @retval 0 success 142 * @retval non-zero if an error occurs initializing the EROM parser, 143 * a regular unix error code will be returned. 144 */ 145METHOD int init_static { 146 bhnd_erom_t *erom; 147 const struct bhnd_chipid *cid; 148 bus_space_tag_t bst; 149 bus_space_handle_t bsh; 150}; 151 152/** 153 * Release all resources held by @p erom. 154 * 155 * @param erom An erom parser instance previously initialized via 156 * BHND_EROM_INIT() or BHND_EROM_INIT_STATIC(). 157 */ 158METHOD void fini { 159 bhnd_erom_t *erom; 160}; 161 162/** 163 * Parse all cores descriptors, returning the array in @p cores and the count 164 * in @p num_cores. 165 * 166 * The memory allocated for the table must be freed via 167 * BHND_EROM_FREE_CORE_TABLE(). 168 * 169 * @param erom The erom parser to be queried. 170 * @param[out] cores The table of parsed core descriptors. 171 * @param[out] num_cores The number of core records in @p cores. 172 * 173 * @retval 0 success 174 * @retval non-zero if an error occurs, a regular unix error code will 175 * be returned. 176 */ 177METHOD int get_core_table { 178 bhnd_erom_t *erom; 179 struct bhnd_core_info **cores; 180 u_int *num_cores; 181}; 182 183/** 184 * Free any memory allocated in a previous call to BHND_EROM_GET_CORE_TABLE(). 185 * 186 * @param erom The erom parser instance. 187 * @param cores A core table allocated by @p erom. 188 */ 189METHOD void free_core_table { 190 bhnd_erom_t *erom; 191 struct bhnd_core_info *cores; 192}; 193 194/** 195 * Locate the first core table entry in @p erom that matches @p desc. 196 * 197 * @param erom The erom parser to be queried. 198 * @param desc A core match descriptor. 199 * @param[out] core On success, the matching core info record. 200 * 201 * @retval 0 success 202 * @retval ENOENT No core matching @p desc was found. 203 * @retval non-zero Reading or parsing failed. 204 */ 205METHOD int lookup_core { 206 bhnd_erom_t *erom; 207 const struct bhnd_core_match *desc; 208 struct bhnd_core_info *core; 209}; 210 211/** 212 * Locate the first core table entry in @p erom that matches @p desc, 213 * and return the specified port region's base address and size. 214 * 215 * If a core matching @p desc is not found, or the requested port region 216 * is not mapped to the matching core, ENOENT is returned. 217 * 218 * @param erom The erom parser to be queried. 219 * @param desc A core match descriptor. 220 * @param type The port type to search for. 221 * @param port The port to search for. 222 * @param region The port region to search for. 223 * @param[out] core If not NULL, will be populated with the matched core 224 * info record on success. 225 * @param[out] addr On success, the base address of the port region. 226 * @param[out] size On success, the total size of the port region. 227 * 228 * @retval 0 success 229 * @retval ENOENT No core matching @p desc was found. 230 * @retval ENOENT No port region matching @p type, @p port, and @p region 231 * was found. 232 * @retval non-zero Reading or parsing failed. 233 */ 234METHOD int lookup_core_addr { 235 bhnd_erom_t *erom; 236 const struct bhnd_core_match *desc; 237 bhnd_port_type type; 238 u_int port; 239 u_int region; 240 struct bhnd_core_info *core; 241 bhnd_addr_t *addr; 242 bhnd_size_t *size; 243}; 244 245/** 246 * Enumerate and print all EROM table entries. 247 * 248 * @param erom The erom parser to be enumerated. 249 * 250 * @retval 0 success 251 * @retval non-zero If an error occurs reading the EROM table, a regular 252 * unix error code will be returned. 253 */ 254METHOD int dump { 255 bhnd_erom_t *erom; 256}; 257