home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / catD / hwgraph.intro.z / hwgraph.intro
Encoding:
Text File  |  1998-10-30  |  9.5 KB  |  199 lines
  1.  
  2.  
  3.  
  4. hhhhwwwwggggrrrraaaapppphhhh....iiiinnnnttttrrrroooo((((DDDD3333XXXX))))                                          hhhhwwwwggggrrrraaaapppphhhh....iiiinnnnttttrrrroooo((((DDDD3333XXXX))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      hwgraph_intro - hardware graph overview for device driver writers
  10.  
  11. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  12.      The system hardware graph (briefly, hwgraph) represents the collection of
  13.      all significant hardware connected to a system.  It represents each piece
  14.      of hardware -- each module, CPU, memory, disk controller, disk drive,
  15.      disk partition, serial port, ethernet port, etc.  -- as a distinct vertex
  16.      in the graph.  There are additional vertexes that represent collections
  17.      of hardware (for example, "the disks") or more abstract architectural
  18.      concepts (for example, "a node").
  19.  
  20.      Because the hwgraph is the whole representation of the hardware, a device
  21.      driver needs to use, and sometimes to create, vertexes in the hwgraph.
  22.      It takes relatively little effort to create a hardware graph-aware IRIX
  23.      device driver, and this is necessary in order to take advantage of many
  24.      kernel interfaces.
  25.  
  26.      This section describes the basics of the system hardware graph, (briefly,
  27.      hwgraph), from the perspective of a device driver writer.  Other man
  28.      pages listed below describe the exact interfaces.  Additional overview
  29.      from the user's perspective is found in _h_w_g_r_a_p_h(4), which should be read
  30.      first.
  31.  
  32.    vvvveeeerrrrtttteeeexxxx____hhhhddddllll____tttt TTTTyyyyppppeeee
  33.      A _v_e_r_t_e_x__h_d_l__t is a 32-bit integer that uniquely identifies an instance
  34.      of a device.  The device driver uses the vertex_hdl_t to identify a
  35.      device and to locate and exploit the hwgraph vertex that describes the
  36.      device.
  37.  
  38.      Because it is the same base type and size as a _d_e_v__t and serves the same
  39.      purpose, a vertex_hdl_t is a variety of dev_t.  Most interfaces that
  40.      accept a dev_t as parameter actually require a vertex_hdl_t.
  41.  
  42.    OOOOppppeeeerrrraaaattttiiiioooonnnnssss
  43.      There are many operations to manipulate the hardware graph (and
  44.      implicitly, the "/hw" filesystem).  There are operations to create and
  45.      destroy vertexes and labeled edges, to associate labeled and unlabeled
  46.      information with a vertex and to later retrieve it, to retrieve
  47.      administrative information associated with a vertex, and to create
  48.      vertexes that represent block and char devices.
  49.  
  50.    TTTTyyyyppppiiiiccccaaaallll UUUUssssaaaaggggeeee
  51.      The best way to understand how the hwgraph and /hw filesystem work is
  52.      through a simple example for an imaginary XYZ device that sits on, say, a
  53.      PCI bus.  Say that the device driver's prefix is "XYZ_"; say that the
  54.      XYZ_ driver is statically linked into the kernel (just for simplicity's
  55.      sake); and say that the XYZ_ driver supports only a "char" interface.
  56.  
  57.      Very early in the boot processes, _X_Y_Z__i_n_i_t() is called.  This entry point
  58.      calls _p_c_i_i_o__d_r_i_v_e_r__r_e_g_i_s_t_e_r() (see _p_c_i_i_o(D3)) to tell the PCI
  59.      infrastructure which PCI Device ID and Vendor ID the driver handles.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. hhhhwwwwggggrrrraaaapppphhhh....iiiinnnnttttrrrroooo((((DDDD3333XXXX))))                                          hhhhwwwwggggrrrraaaapppphhhh....iiiinnnnttttrrrroooo((((DDDD3333XXXX))))
  71.  
  72.  
  73.  
  74.      Later in the boot process, the system probes for I/O.  On multiprocessor
  75.      systems, I/O probing may be done by multiple CPUs on multiple I/O boards
  76.      simultaneously.  When a PCI bus is found, the PCI infrastructure
  77.      discovers the Device ID and Vendor ID of every device on that bus and
  78.      calls the _a_t_t_a_c_h() entry point of any driver that has previously
  79.      registered to handle those IDs.  In this case, the PCI infrastructure
  80.      invokes _X_Y_Z__a_t_t_a_c_h().
  81.  
  82.      The _X_Y_Z__a_t_t_a_c_h routine allocates and initializes a per-device structure,
  83.      XYZ_info.  It then creates a char device vertex (and implicitly, a char
  84.      device special file) using _h_w_g_r_a_p_h__c_h_a_r__d_e_v_i_c_e__a_d_d().  _X_Y_Z__a_t_t_a_c_h uses
  85.      its dev_t parameter as the vertex_hdl_t parameter passed to
  86.      _h_w_g_r_a_p_h__c_h_a_r__d_e_v_i_c_e__a_d_d().  Additionally, the XYZ_ driver must use that
  87.      same dev_t whenever it requests service of any kind (DMA mapping, PIO
  88.      mapping, interrupt management, etc.)  from the PCI infrastructure.
  89.      Therefore, the XYZ_ driver saves that dev_t in a field of the per-device
  90.      structure it allocated earlier.
  91.  
  92.      _h_w_g_r_a_p_h__c_h_a_r__d_e_v_i_c_e__a_d_d() returns a vertex_hdl_t (dev_t) to _X_Y_Z__a_t_t_a_c_h().
  93.      This is the dev_t parameter that the driver will receive in its
  94.      _X_Y_Z__o_p_e_n() entry point if the special file is ever opened.
  95.  
  96.      Finally, _X_Y_Z__a_t_t_a_c_h() calls _d_e_v_i_c_e__i_n_f_o__s_e_t() to associate a pointer to
  97.      the per-device XYZ_info structure with the vertex_hdl_t returned from
  98.      _h_w_g_r_a_p_h__c_h_a_r__d_e_v_i_c_e__a_d_d(), and possibly _d_e_v_i_c_e__i_n_v_e_n_t_o_r_y__a_d_d() to attach
  99.      hardware inventory information.
  100.  
  101.      After the system finishes booting, users will find somewhere under /hw a
  102.      char device special file.  This is the user-visible effect of the
  103.      driver's call to _h_w_g_r_a_p_h__c_h_a_r__d_e_v_i_c_e__a_d_d().  When the user opens this
  104.      special file, the system ends up in _X_Y_Z__o_p_e_n().  The first parameter is a
  105.      dev_t (vertex_hdl_t).  _X_Y_Z__o_p_e_n() uses _d_e_v_i_c_e__i_n_f_o__g_e_t() with this dev_t
  106.      to retrieve the per-device XYZ_info structure it allocated and
  107.      initialized at attach time.  One of the fields of this structure is the
  108.      vertex_hdl_t (dev_t) that was passed to _X_Y_Z__a_t_t_a_c_h(), and which is needed
  109.      for service from the PCI support code.
  110.  
  111.    DDDDeeeebbbbuuuuggggggggiiiinnnngggg SSSSuuuuppppppppoooorrrrtttt
  112.      At any point, the driver can print the "canonical device name" of a
  113.      vertex_hdl_t using the "%v" conversion specification in a _c_m_n__e_r_r()
  114.      format string.  For example,
  115.  
  116.                cmn_err(CE_WARN, "....foo....%v....bar....", dev);
  117.  
  118.  
  119.    RRRReeeeffffeeeerrrreeeennnncccceeee CCCCoooouuuunnnnttttssss
  120.      The hwgraph interfaces track references to vertexes.  When and only when
  121.      the reference count drops to 0, the vertex is deleted.  A newly-created
  122.      vertex starts with a count of 1.  Any interface that returns a vertex
  123.      handle increments the reference count on the associated vertex.  An
  124.      explicit invocation of _h_w_g_r_a_p_h__v_e_r_t_e_x__r_e_f() increments a reference count,
  125.      and an explicit invocation of _h_w_g_r_a_p_h__v_e_r_t_e_x__u_n_r_e_f() decrements a
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. hhhhwwwwggggrrrraaaapppphhhh....iiiinnnnttttrrrroooo((((DDDD3333XXXX))))                                          hhhhwwwwggggrrrraaaapppphhhh....iiiinnnnttttrrrroooo((((DDDD3333XXXX))))
  137.  
  138.  
  139.  
  140.      reference count.  _h_w_g_r_a_p_h__v_e_r_t_e_x__d_e_s_t_r_o_y() automatically decrements the
  141.      reference count.  When an edge is added to a vertex, the reference count
  142.      of the destination vertex is incremented.  Conversely, when an edge is
  143.      removed, the destination vertex's reference count is decremented.
  144.  
  145.      For the normal and simple case, drivers do not need to explicitly add
  146.      edges or destroy vertexes, so reference counting is irrelevant.  When it
  147.      is necessary to explicitly destroy a vertex, the driver should first
  148.      remove all edges that point to it and all edges that start from it.
  149.  
  150. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  151.      Many hwgraph_* interfaces return a small integer type, graph_error_t,
  152.      that is defined in sys/graph.h and includes these values:
  153.  
  154.      GRAPH_SUCCESS
  155.                  Operation completed normally and successfully.
  156.  
  157.      GRAPH_DUP   Operation tried to create something that already existed.
  158.  
  159.      GRAPH_NOT_FOUND
  160.                  Operation searched for something that could not be found.
  161.  
  162.      GRAPH_BAD_PARAM
  163.                  An invalid parameter was supplied.
  164.  
  165.      GRAPH_HIT_LIMIT
  166.                  An iterative operation reached the end of the list.
  167.  
  168.      GRAPH_IN_USE
  169.                  Attempt to destroy a vertex that is still in use.
  170.  
  171. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  172.      hwgraph(4), cmn_err(D3), hwgraph.admin(D3X), hwgraph.dev(D3X),
  173.      hwgraph.edge(D3X), hwgraph.inv(D3X), hwgraph.lblinfo(D3X),
  174.      hwgraph.vertex(D3X).
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.