.. _nv3-pgraph:

=================================
NV3 PGRAPH: 2d/3d graphics engine
=================================

.. contents::


Introduction
============

.. todo:: write me


MMIO registers
==============

.. space:: 8 nv3-pgraph 0x1000 2d/3d graphics engine
   0x100 INTR nv1-pgraph-intr
   0x104 INVALID nv1-pgraph-invalid
   0x140 INTR_EN nv1-pgraph-intr-en
   0x144 INVALID_EN nv1-pgraph-invalid-en

.. todo:: finish me


.. _nv3-pgraph-intr:

Interrupts
==========

The PGRAPH registers dealing with interrupts are:

.. reg:: 32 nv3-pgraph-intr Interrupt status

  Status of interrupts generated by PGRAPH. On read, returns 1 for bits
  corresponding to pending interrupts. On write, if 1 is written to a bit,
  its interrupt gets cleared, if 0 is written nothing happens.

  - bit 0: INVALID - something was wrong with the submitted method. Detailed
    status is available in the INVALID register. Clearing this bit will also
    clear the INVALID register. In turn, clearing the INVALID register will
    clear this bit.
  - bit 4: CONTEXT_SWITCH - a CTX_SWITCH method was submitted and the channel
    id and/or SUBCONTEXT_ID is different from the current one.
  - bit 8: VBLANK - the vertical blanking period has started on PFB. This
    is really PFB's interrupt. It is delivered to a different PMC line than
    other PGRAPH interrupts. See :ref:`NV1 PFB <nv1-pfb>` for details.
  - bit 12: XY_RANGE - an X or Y coordinate used for rendering was out of the
    -0x8000..0x7fff range supported by the rasterizer
  - bit 16: MISSING_METHOD - the final method to do an operation was submitted
    without first submitting other required methods
  - bit 20: MISSING_FORMAT - the format of the destination surface is not
    supported by PGRAPH.
  - bit 24: CLIP_SOFTWARE - a drawing operation was attempted with SOFTWARE bit
    set in CLIPRECT_CTRL.
  - bit 28: NOTIFY - a method on which notify interrupt was requested has been
    executed

.. reg:: 32 nv3-pgraph-intr-en Interrupt enable

  Interrupt enable bitmask. Set to enable, clear to disable. Interrupts that
  are masked will still show up in INTR when they're triggered, but won't
  cause the PGRAPH or PFB interrupt line to go active. Has same bitfields
  as INTR.

Interrupts other than VBLANK are delivered to PMC interrupt line 12. VBLANK
interrupt is delivered to PMC interrupt line 24.

The INVALID interrupt is further controlled by these registers:

.. reg:: 32 nv3-pgraph-invalid INVALID interrupt status

  Status of INVALID subinterrupts. Works like INTR. Clearing this register
  will also clear the INVALID bit in INTR register. In turn, clearing INVALID
  bit in INTR will also clear this register.

  - bit 0: INVALID_METHOD - the method that was submitted does not exist
  - bit 4: INVALID_VALUE - the method was submitted with invalid parameter
  - bit 8: INVALID_NOTIFY - a NOTIFY method was submitted, but NOTIFY_VALID
    was not set in graph object options
  - bit 12: DOUBLE_NOTIFY - a NOTIFY method was submitted with NOTIFY_PENDING
    already set
  - bit 16: CTXSW_NOTIFY - a CTX_SWITCH method was submitted with NOTIFY_PENDING
    set

.. reg:: 32 nv3-pgraph-invalid-en INVALID interrupt enable

  INVALID interrupt enable bitmask. Set to enable, clear to disable. Same
  bitfields as INVALID. If any interrupt active in INVALID is also enabled
  here, interrupt line to PMC will be active. Note that this register does
  *not* affect triggering the INVALID bit in INTR and the interrupt status
  from INTR&INTR_EN will be effectively ORed with INVALID&INVALID_EN. Thus
  the contents of INVALID_EN will only matter when INTR_EN.INVALID is set
  to 0.

The INTR and INVALID registers are special and can be written by host even
if ACCESS.HOST is not set.

Note that interrupts that are disabled will still cause PGRAPH to halt and
disable FIFO/HOST bits in ACCESS.


Method submission
=================

.. todo:: write me


Graph objects
=============

On NV3, object options were expanded and moved to a memory structure in
RAMIN. The data stored in RAMHT and passed to PGRAPH is just a [shifted]
pointer to the grobj structure. Most importantly, the DMA objects bound
to the graph object are now stored in the options structure and don't have
to be swapped by software on every graphics object switch. The graph
object options structure is made of 3 32-bit words aligned on 0x10-byte
bounduary:

word 0:
  ???
  
.. todo:: figure out the bits, should be similiar to the NV1 options

word 1:
  - bits 0-15: main DMA object. This is used for GDI, SIFM, ITM, D3D, M2MF.
    For M2MF, this is the source DMA object.
  - bits 16-31: NOTIFY DMA object.

.. todo:: check M2MF source

word 2:
  - bits 0-15: secondary DMA object. This is used for M2MF destination DMA
    object.
    
.. todo:: check

The options structure, and thus also the graph object, is selected by the
structure address in RAMIN shifted right by 4 bits. Thus graph object 0x1234
has its options structure at RAMIN address 0x12340.


Context
=======

.. todo:: write me


Surface setup
=============

.. todo:: write me


Drawing operation
=================

.. todo:: write me