sys/dev/bhnd/bhnd_erom_if.m

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