sys/dev/bhnd/bhnd_erom_if.m

   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
  37 INTERFACE 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  */
  68 STATICMETHOD 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  */
 101 STATICMETHOD 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  */
 124 METHOD 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  */
 145 METHOD 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  */
 158 METHOD 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  */
 177 METHOD 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  */
 189 METHOD 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  */
 205 METHOD 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  */
 234 METHOD 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  */
 254 METHOD int dump {
 255         bhnd_erom_t                     *erom;
 256 };