Reading and copying from banked memory.

APIs for indirect access to banked memory. More...

Collaboration diagram for Reading and copying from banked memory.:

Functions
uint8_t	bmem_get (bmemptr_t src)
	Read byte from banked memory.
uint16_t	bmem_get_u16 (bmemptr_t src)
	Read 16-bits value from banked memory.
void	bmem_read (bmemptr_t src, void *dst, uint16_t len)
	Read byte sequence from banked memory.
void	bmem_copy_to_vmem (bmemptr_t src, vmemptr_t dst, uint32_t len)
	Copy from banked memory to VRAM.
void	bmem_bload_s (bmemptr_t src)
	Load a BSAVE formatted binary in banked memory into VRAM.
void	bmem_bload (bmemptr_t src, void *buf, size_t buf_size)
	Load a BSAVE formatted binary in banked memory into RAM.

Detailed Description

APIs for indirect access to banked memory.

Banked memory is treated as a ROM with one large address space to read and copy data.

Function Documentation

bmem_get()

uint8_t bmem_get

(

bmemptr_t

src

)

Read byte from banked memory.

Parameters

src	address of banked memory.

Returns

a byte value.

bmem_get_u16()

uint16_t bmem_get_u16

(

bmemptr_t

src

)

Read 16-bits value from banked memory.

Parameters

src	address of banked memory.

Returns

a 16-bits value.

bmem_read()

void bmem_read	(	bmemptr_t	src,
		void *	dst,
		uint16_t	len )

Read byte sequence from banked memory.

Parameters

src	source address of banked memory.
dst	destination address.
len	number of bytes to be read.

Note

This function is supposed to copy from banked memory to page 3 of main RAM. Thus the destination area specified by dst and len must be in range of 0xc000 to 0xfffe. In libmsx, the DATA segment and stack areas are placed on page 3 so this is reasonable.

In particular, page 2 is used to access banked memory so the destination areas cannot be in page 2. Page 0 is MAIN ROM, page 1 is CODE segment, and the library code itself is included in CODE segment. So these areas cannot be specified as the destination areas.

Address 0xffff is not memory, that is "extended slot selector" register.

Attention

Stack areas and work areas are overridden if they intersect the destination area specified by dst and len. Unfortunately, however, the library cannot determine the appropriate bounds. The application programmer must deal with this.

bmem_copy_to_vmem()

void bmem_copy_to_vmem	(	bmemptr_t	src,
		vmemptr_t	dst,
		uint32_t	len )

Copy from banked memory to VRAM.

Parameters

src	source address of banked memory.
dst	destination address of VRAM.
len	number of bytes to be copied.

bmem_bload_s()

void bmem_bload_s

(

bmemptr_t

src

)

Load a BSAVE formatted binary in banked memory into VRAM.

A BSAVE formatted binary must consist of a 7-byte header followed by the data body, as follows:

address	contents
src+0	0xFE
src+1	lo-byte of start address
src+2	hi-byte of start address
src+3	lo-byte of end address
src+4	hi-byte of end address
src+5	lo-byte of run address
src+6	hi-byte of run address
src+7	body[0]
...	...
src+7 + N-1	body[N-1]

where N == end - start + 1, and start <= end.

start and end indicate the range of VRAM addresses where the image was; for VRAM images, run is not used.

This function copies the data body to start..end of VRAM.

Parameters

src	address of BSAVE foramtted binary in banked memory.

bmem_bload()

void bmem_bload	(	bmemptr_t	src,
		void *	buf,
		size_t	buf_size )

Load a BSAVE formatted binary in banked memory into RAM.

A BSAVE formatted binary must consist of a 7-byte header followed by the data body, as follows:

address	contents
src+0	0xFE
src+1	lo-byte of start address
src+2	hi-byte of start address
src+3	lo-byte of end address
src+4	hi-byte of end address
src+5	lo-byte of run address
src+6	hi-byte of run address
src+7	body[0]
...	...
src+7 + N-1	body[N-1]

where N == end - start + 1, and start <= end.

start and end are the range of addresses where the data body was, and run is the address of the entry point (ignored by libmsx).

This function copies the body of the data to the specified buffer starting with buf.

Do nothing in the following cases

• The data pointed by src is not a BSAVE formatted binary.
• Buffer size is too small.

Parameters

src	Address of BSAVE foramtted binary in banked memory.
buf	Pointer to the RAM buffer.
buf_size	Buffer size (i.e., capacity) in bytes.

Note

This function is supposed to copy from banked memory to page 3 of main RAM. Thus the buffer specified by buf and buf_size must be in range of 0xc000 to 0xfffe. In libmsx, the DATA segment and stack areas are placed on page 3 so this is reasonable.

In particular, page 2 is used to access banked memory so the buffer cannot be in page 2. Page 0 is MAIN ROM, page 1 is CODE segment, and the library code itself is included in CODE segment. So these areas cannot be specified as the buffer.

Address 0xffff is not memory, that is "extended slot selector" register.

Attention

Stack areas and work areas are overridden if they intersect the buffer specified by buf and buf_size. Unfortunately, however, the library cannot determine the appropriate bounds. The application programmer must deal with this.

See also

bmem_read()