@database "potgo"
@master "AMIDEV:NDK/Autodocs/potgo.doc"

@Node Main "potgo.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" AllocPotBits() " Link "AllocPotBits()"}
    @{" FreePotBits() " Link "FreePotBits()"}
    @{" WritePotgo() " Link "WritePotgo()"}
@EndNode

@Node "AllocPotBits()" "potgo.resource/AllocPotBits"

@{b}   NAME@{ub}
	AllocPotBits -- @{"Allocate" Link "exec/Allocate()"} bits in the potgo register.

@{b}   SYNOPSIS@{ub}
	allocated = AllocPotBits(bits)
	D0                       D0

	@{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} AllocPotBits( @{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} );

@{b}   FUNCTION@{ub}
	The AllocPotBits routine allocates bits in the hardware potgo
	register that the application wishes to manipulate via
	@{"WritePotgo" Link "potgo/WritePotgo()"}.  The request may be for more than one bit.  A
	user trying to allocate bits may find that they are
	unavailable because they are already allocated, or because
	the start bit itself (bit 0) has been allocated, or if
	requesting the start bit, because input bits have been
	allocated.  A user can block itself from allocation: i.e.
	it should FreePotgoBits the bits it has and re-AllocPotBits if
	it is trying to change an allocation involving the start bit.

@{b}   INPUTS@{ub}
	bits - a description of the hardware bits that the application
		wishes to manipulate, loosely based on the register
		description itself:
	    START (bit 0) - set if you wish to use start (i.e. start
		    the proportional controller counters) with the
		    input ports you allocate (below).  You must
		    allocate all the DATxx ports you want to apply
		    START to in this same call, with the OUTxx bit
		    clear.
	    DATLX (bit 8) - set if you wish to use the port associated
		    with the left (0) controller, pin 5.
	    OUTLX (bit 9) - set if you promise to use the LX port in
		    output mode only.  The port is not set to output
		    for you at this time -- this bit set indicates
		    that you don't mind if STARTs are initiated at any
		    time by others, since ports that are enabled for
		    output are unaffected by START.
	    DATLY (bit 10) - as DATLX but for the left (0) controller,
		    pin 9.
	    OUTLY (bit 11) - as OUTLX but for LY.
	    DATRX (bit 12) - the right (1) controller, pin 5.
	    OUTRX (bit 13) - OUT for RX.
	    DATRY (bit 14) - the right (1) controller, pin 9.
	    OUTRY (bit 15) - OUT for RY.

@{b}   RESULTS@{ub}
	allocated - the START and DATxx bits of those requested that
		were granted.  The OUTxx bits are don't cares.

@EndNode

@Node "FreePotBits()" "potgo.resource/FreePotBits"

@{b}   NAME@{ub}
	FreePotBits -- Free allocated bits in the potgo register.

@{b}   SYNOPSIS@{ub}
	FreePotBits(allocated)
	            D0

	void FreePotBits( @{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} );

@{b}   FUNCTION@{ub}
	The FreePotBits routine frees previously allocated bits in the
	hardware potgo register that the application had allocated via
	@{"AllocPotBits" Link "potgo/AllocPotBits()"} and no longer wishes to use.  It accepts the
	return value from @{"AllocPotBits" Link "potgo/AllocPotBits()"} as its argument.

@EndNode

@Node "WritePotgo()" "potgo.resource/WritePotgo"

@{b}   NAME@{ub}
	WritePotgo -- @{"Write" Link "dos/Write()"} to the hardware potgo register.

@{b}   SYNOPSIS@{ub}
	WritePotgo(word, mask)
	           D0    D1

	void WritePotgo( @{"UWORD" Link "INCLUDE:exec/types.h/Main" 116}, @{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} );

@{b}   FUNCTION@{ub}
	The WritePotgo routine sets and clears bits in the hardware
	potgo register.  Only those bits specified by the mask are
	affected -- it is improper to set bits in the mask that you
	have not successfully allocated.  The bits in the high byte
	are saved to be maintained when other users write to the
	potgo register.  The START bit is not saved, it is written
	only explicitly as the result of a call to this routine with
	the START bit set: other users will not restart it.

@{b}   INPUTS@{ub}
	word - the data to write to the hardware potgo register and
	    save for further use, except the START bit, which is
	    not saved.
	mask - those bits in word that are to be written.  Other
	    bits may have been provided by previous calls to
	    this routine, and default to zero.

@EndNode