Document IOP BIOS API used by modules

[frno7]

Write RST reference documentation for the IOP BIOS API used by modules in this repository:

• INTRMAN
• LOADCORE
• SIFCMD
• SIFMAN
• THBASE

Also:

• License reference documentation so that it easily can be shared with PS2SDK. Dual licence? Which ones?

[AKuHAK]

You can review this information. This is developed by creators of DobieStation (PS2 emulator).

[frno7]

Thank you, @AKuHAK. I was aware of those function prototypes, see previous link to the ps2tek document in the conversation frno7/linux#22 (comment)! Unfortunately, a lot of essential details are missing. Here are two examples of reference documentation, for a structure and a function, with more details filled in that are similar to how the IOP BIOS is planned to be documented:

iopmod/include/iopmod/sifcmd.h

Lines 43 to 58 in a5d2360

	/**
	* struct sif_cmd_header - 16-byte SIF command header
	* @packet_size: min 1x16 for header only, max 7*16 bytes
	* @data_size: main processor data size in bytes
	* @data_addr: main processor data address or zero
	* @cmd: command number
	* @opt: optional argument
	*/
	struct sif_cmd_header
	{
	u32 packet_size : 8;
	u32 data_size : 24;
	u32 data_addr;
	u32 cmd;
	u32 opt;
	} __attribute__((aligned(4)));

iopmod/include/iopmod/sif.h

Lines 15 to 36 in a5d2360

	/**
	* sif_cmd_data - send command over the SIF
	* @cmd: command number
	* @payload: pointer to payload, any alignment
	* @payload_size: payload size, maximum %CMD_PACKET_PAYLOAD_MAX bytes
	* @dst: destination address on main processor, 16-byte aligned, or zero
	* @src: source address on sub processor, 4-byte aligned, or %NULL
	* @nbytes: number of bytes to copy from @src to @dst, or zero
	*
	* Waits for DMA completion. Note that @nbytes will be rounded up to 16-byte
	* alignment, so the destination buffer must accommodate for that.
	*
	* Context: any
	* Return: 0 on success, otherwise a negative error number
	*/
	static inline int sif_cmd_data(u32 cmd_id,
	const void *payload, size_t payload_size,
	main_addr_t dst, const void *src, size_t nbytes)
	{
	return sif_cmd_opt_data(cmd_id, 0,
	payload, payload_size, dst, src, nbytes);
	}

[frno7]

Boosting interrupt related documentation in commits 1cce6fc and 95d5fa5.

[frno7]

Does anyone know of reasonable descriptions of these SIF DMA attributes, used with sceSifSetDma and its array of SifDmaTransfer_t structures? PS2SDK doesn’t seem to say anything about them.

iopmod/include/iopmod/sifman.h

Lines 8 to 20 in 4f0dc8c

	/**
	* enum sif_dma_attr - DMA transfer completion attributes
	* @SIF_DMA_ATTR_INT_I: FIXME
	* @SIF_DMA_ATTR_INT_O: assert IOP interrupt on completion
	* @SIF_DMA_ATTR_ERT: FIXME
	*
	* Attributes may be combined into a set by logical or.
	*/
	enum sif_dma_attr {
	SIF_DMA_ATTR_INT_I = 0x02,
	SIF_DMA_ATTR_INT_O = 0x04,
	SIF_DMA_ATTR_ERT = 0x40,
	};

Perhaps ERT is something like @wisi-w described in IOP_DMAC.txt?

DMA_ERT End Reference Transfer (guess) ("ref" is the EE tag ID that resembles the way the IOP tag works). Once the transfer of the data of the tag with this flag is complete, the DMA channel is stopped: The CHCR.24 (DMA channel active) is cleared and in the case of the SIF channels, the corresponding IOP-bit in BD4 (BD4.5:4) is cleared as well. A DMA-completion interrupt is triggered on transfer completion as usual.