share/man/man9/ofw_graph.9

   1 .\" Copyright (c) 2019 Emmanuel Vadot <manu@freebsd.org>
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  13 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  14 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  15 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  16 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  17 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  18 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  19 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  20 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  21 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  22 .\"
  23 .\" $FreeBSD$
  24 .\"
  25 .Dd April 10, 2019
  26 .Dt ofw_graph 9
  27 .Os
  28 .Sh NAME
  29 .Nm ofw_graph ,
  30 .Nm ofw_graph_get_port_by_idx ,
  31 .Nm ofw_graph_port_get_num_endpoints ,
  32 .Nm ofw_graph_get_endpoint_by_idx ,
  33 .Nm ofw_graph_get_remote_endpoint ,
  34 .Nm ofw_graph_get_remote_parent ,
  35 .Nm ofw_graph_get_device_by_port_ep ,
  36 .Nd Helpers for the graph bindings
  37 .Sh SYNOPSIS
  38 .In dev/ofw/openfirm.h
  39 .In dev/ofw/ofw_graph.h
  40 .Ft phandle_t
  41 .Fn ofw_graph_get_port_by_idx "phandle_t node" "uint32_t idx"
  42 .Ft size_t
  43 .Fn ofw_graph_port_get_num_endpoints "phandle_t port"
  44 .Ft phandle_t
  45 .Fn ofw_graph_get_endpoint_by_idx "phandle_t port" "uint32_t idx"
  46 .Ft phandle_t
  47 .Fn ofw_graph_get_remote_endpoint "phandle_t endpoint"
  48 .Ft phandle_t
  49 .Fn ofw_graph_get_remote_parent "phandle_t remote"
  50 .Ft device_t
  51 .Fn ofw_graph_get_device_by_port_ep "phandle_t node" "uint32_t port_id" "uin32_t ep_id"
  52 .Sh DESCRIPTION
  53 .Pp
  54 The ofw_graph functions are helpers to parse the DTS graph bindings
  55 .Pp
  56 .Fn ofw_graph_get_port_by_idx
  57 return the port with id
  58 .Fa idx .
  59 It will first check node named
  60 .Fa port@idx
  61 and then fallback on checking the
  62 .Fa ports
  63 child for a child node matching the id.
  64 If no ports matching
  65 .Fa idx
  66 is found the function return 0.
  67 .Pp
  68 .Fn ofw_graph_port_get_num_endpoints
  69 returns the number of endpoints a port node have.
  70 .Pp
  71 .Fn ofw_graph_get_endpoint_by_idx
  72 return the endpoint with id
  73 .Fa idx .
  74 It will first check if there is a single child named
  75 .Fa endpoint
  76 and returns it if there is.
  77 If there is multiple endpoints it will check the
  78 .Fa reg
  79 property and returns the correct
  80 .Fa phandle_t
  81 or 0 if none match.
  82 .Pp
  83 .Fn ofw_graph_get_remote_endpoint
  84 returns the
  85 .Fa remote-endpoint
  86 property if it exists or 0.
  87 .Pp
  88 .Fn ofw_graph_get_remote_parent
  89 returns the device node corresponding to the
  90 .Fa remote-endpoint
  91 phandle or 0 if none.
  92 .Fn ofw_graph_get_device_by_port_ep
  93 returns the device associated with the port and endpoint or
  94 .Fa NULL
  95 if none.
  96 The device driver should have called
  97 .Fn OF_device_register_xref
  98 before.
  99 .Fn
 100 .Sh HISTORY
 101 The
 102 .Nm ofw_graph
 103 functions first appeared in
 104 .Fx 13.0 .
 105 The
 106 .Nm ofw_graph
 107 functions and manual page were written by
 108 .An Emmanuel Vadot Aq Mt manu@FreeBSD.org .