Menu
▾
▴
[cadcdev-svn-commits] [SCM] branch master updated. v2.0.0-46-gdcbe259
|
From: Lawrence S. <ljs...@us...> - 2014-03-15 02:35:37
|
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "A pseudo Operating System for the Dreamcast.".
The branch, master has been updated
via dcbe25916d0cca0bc02310a4de9b217b020507ab (commit)
from abd905c6a87e888d0abef384e83acfdbb7df339d (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit dcbe25916d0cca0bc02310a4de9b217b020507ab
Author: Lawrence Sebald <ljs...@us...>
Date: Fri Mar 14 22:34:39 2014 -0400
Add documentation for the addons tree, and adjust the Doxyfile so it will generate said documentation.
-----------------------------------------------------------------------
Summary of changes:
addons/include/ext2/fs_ext2.h | 3 -
addons/include/kos/bspline.h | 51 ++++++++----
addons/include/kos/img.h | 186 +++++++++++++++++++++++++++++++---------
addons/include/kos/md5.h | 54 +++++++++++-
addons/include/kos/netcfg.h | 159 +++++++++++++++++++++++++++--------
addons/include/kos/pcx.h | 51 +++++++++--
addons/include/kos/vector.h | 28 +++++--
doc/Doxyfile | 38 +--------
8 files changed, 419 insertions(+), 151 deletions(-)
diff --git a/addons/include/ext2/fs_ext2.h b/addons/include/ext2/fs_ext2.h
index e0803de..39932aa 100644
--- a/addons/include/ext2/fs_ext2.h
+++ b/addons/include/ext2/fs_ext2.h
@@ -43,9 +43,6 @@ __BEGIN_DECLS
the ext2fs layer anyway, as this layer should give you everything you need
by interfacing with the VFS in the normal fashion.
- Also, at the moment, this is a read-only filesystem. Write support will be
- forthcoming, but it may take a bit of time to get completely working.
-
There's one final note that I should make. Everything in fs_ext2 and ext2fs
is licensed under the same license as the rest of KOS. None of it was
derived from GPLed sources. Pretty much all of what's in ext2fs was written
diff --git a/addons/include/kos/bspline.h b/addons/include/kos/bspline.h
index 8ba59d9..cfae65a 100644
--- a/addons/include/kos/bspline.h
+++ b/addons/include/kos/bspline.h
@@ -1,37 +1,54 @@
/* KallistiOS ##version##
bspline.h
- (c)2000 Dan Potter
+ Copyright (C) 2000 Dan Potter
*/
#ifndef __KOS_BSPLINE_H
#define __KOS_BSPLINE_H
-#include <sys/cdefs.h>
-__BEGIN_DECLS
+/** \file kos/bspline.h
+ \brief B-Spline curve support.
+
+ This module provides utility functions to generate b-spline curves in your
+ program. It is used by passing in a set of control points to
+ bspline_coeff(), and then querying for individual points using
+ bspline_get_point().
-/** \file
- This module provides utility functions to generate b-spline
- curves in your program. It is used by passing in a set of
- control points to bspline_coeff, and then querying for
- individual points using bspline_get_point.
+ Note that this module is NOT thread-safe.
+
+ \author Dan Potter
*/
+#include <sys/cdefs.h>
+__BEGIN_DECLS
+
#include <kos/vector.h>
-/**
- Pass it an array of points and it will calculate a set of B-spline
- co-efficients for generating a curve. There must be at least one point
- before the "current" one, and at least two after the "current" one (a
- total of four points required). These values will be used in the
- function below.
+/** \brief Calculate and set b-spline coefficients.
+
+ This function performs the initial setup work of calculating the
+ coefficients needed to generate a b-spline curve for the specified set of
+ points. The calculation is based on a total of 4 points: one previous point,
+ the current point, and two points that occur after the current point.
+
+ The current point should be at pnt[0], the previous at pnt[-1], and the
+ future points should be at pnt[1], and pnt[2]. I repeat: pnt[-1] must be a
+ valid point for this to work properly.
+
+ \param pnt The array of points used to calculate the b-spline
+ coefficients.
*/
void bspline_coeff(const point_t *pnt);
-/**
- Given a 't' (between 0.0f and 1.0f) this will generate the next point
- values for the current set of coefficients.
+/** \brief Generate the next point for the current set of coefficients.
+
+ Given a 't' (between 0.0f and 1.0f) this will generate the next point value
+ for the current set of coefficients.
+
+ \param t The "t" value for the b-spline generation function.
+ \param p Storage for the generated point.
*/
void bspline_get_point(float t, point_t *p);
diff --git a/addons/include/kos/img.h b/addons/include/kos/img.h
index 8193562..80a35c5 100644
--- a/addons/include/kos/img.h
+++ b/addons/include/kos/img.h
@@ -1,66 +1,168 @@
/* KallistiOS ##version##
kos/img.h
- (c)2002 Dan Potter
+ Copyright (C) 2002 Dan Potter
*/
#ifndef __KOS_IMG_H
#define __KOS_IMG_H
+/** \file kos/img.h
+ \brief Platform-independent image type.
+
+ This file provides a platform-independent image type that is designed to
+ hold any sort of textures or other image data. This type contains a very
+ basic description of the image data (width, height, pixel format), as well
+ as the image data itself.
+
+ All of the image-loading libraries in kos-ports should provide a function
+ to load the image data into one of these types.
+
+ \author Dan Potter
+*/
+
#include <sys/cdefs.h>
__BEGIN_DECLS
#include <arch/types.h>
-/* KOS Platform independent image struct; you can use this for textures or
- whatever you feel it's appropriate for. "width" and "height" are as you
- would expect. "format" has a lower-half which is platform independent
- and used to basically describe the contained data; the upper-half is
- platform dependent and can hold anything (so AND it off if you want
- the bottom part). Note that in some of the more obscure formats (like
- the paletted formats) the data interpretation _may_ be platform dependent.
- Thus we also provide a data-length field. */
+/** \brief Platform-indpendent image type.
+
+ You can use this type for textures or whatever you feel it's appropriate
+ for. "width" and "height" are as you would expect. "format" has a lower-half
+ which is platform-independent and used to basically describe the contained
+ data; the upper-half is platform-dependent and can hold anything (so AND it
+ off if you only want the bottom part).
+
+ Note that in some of the more obscure formats (like the paletted formats)
+ the data interpretation may be platform dependent. Thus we also provide a
+ data length field.
+
+ \headerfile kos/img.h
+*/
typedef struct kos_img {
- void * data;
- uint32 w, h;
- uint32 fmt;
- uint32 byte_count;
+ void *data; /**< \brief Image data in the specified format. */
+ uint32 w; /**< \brief Width of the image. */
+ uint32 h; /**< \brief Height of the image. */
+ uint32 fmt; /**< \brief Format of the image data.
+ \see kos_img_fmts
+ \see kos_img_fmt_macros */
+ uint32 byte_count; /**< \brief Length of the image data, in bytes. */
} kos_img_t;
-/* Access to the upper and lower pieces of the format word */
-#define KOS_IMG_FMT_I(x) ((x) & 0xffff) /* Platform independent part */
+/** \defgroup kos_img_fmt_macros Macros for accessing the format of an image
+
+ These macros provide easy access to the fmt field of a kos_img_t object.
+
+ @{
+*/
+/** \brief Read the platform-independent half of the format.
+
+ This macro masks the format of a kos_img_t to give you just the lower half
+ of the value, which contains the platform-independent half of the format.
+
+ \param x An image format (fmt field of a kos_img_t).
+ \return The platform-independent half of the format.
+*/
+#define KOS_IMG_FMT_I(x) ((x) & 0xffff)
+
+/** \brief Read the platform-specific half of the format.
+
+ This macro masks the format of a kos_img_t to give you just the upper half
+ of the value, which contains the platform-specific half of the format.
+
+ \param x An image format (fmt field of a kos_img_t).
+ \return The platform-specific half of the format.
+*/
#define KOS_IMG_FMT_D(x) (((x) >> 16) & 0xffff)
-/* Macro to create a new format word */
+/** \brief Build a format value from a platform-independent half and a
+ platform-specific half of the value.
+
+ This macro combines the platform-independent and platform-specific portions
+ of an image format into a value suitable for storing as the fmt field of a
+ kos_img_t object.
+
+ \param i The platform-independent half of the format.
+ \param d The platform-specific half of the format. This should
+ not be pre-shifted.
+ \return A complete image format value, suitable for placing in
+ the fmt variable of a kos_img_t.
+*/
#define KOS_IMG_FMT(i, d) ( ((i) & 0xffff) | (((d) & 0xffff) << 16) )
-/* Definitions for the plat independent part *************************************/
-
-/* Bitmap formats */
-#define KOS_IMG_FMT_NONE 0x00 /* Undefined */
-#define KOS_IMG_FMT_RGB888 0x01 /* Interleaved r/g/b bytes (24-bit) */
-#define KOS_IMG_FMT_ARGB8888 0x02 /* Interleaved a/r/g/b bytes (32-bit) */
-#define KOS_IMG_FMT_RGB565 0x03 /* r/g/b 5/6/5 (16-bit) */
-#define KOS_IMG_FMT_ARGB4444 0x04 /* a/r/g/b 4/4/4/4 (16-bit) */
-#define KOS_IMG_FMT_ARGB1555 0x05 /* a/r/g/b 1/5/5/5 (16-bit) */
-#define KOS_IMG_FMT_PAL4BPP 0x06 /* Paletted (4-bit) */
-#define KOS_IMG_FMT_PAL8BPP 0x07 /* Paletted (8-bit) */
-#define KOS_IMG_FMT_YUV422 0x08 /* y/u/v 4/2/2 (8-bit) */
-#define KOS_IMG_FMT_BGR565 0x09 /* b/g/r 5/6/5 (16-bit) */
-#define KOS_IMG_FMT_RGBA8888 0x10 /* Interleaved r/g/b/a bytes (32-bit) */
-#define KOS_IMG_FMT_MASK 0xff
-
-/* Misc attributes */
-#define KOS_IMG_INVERTED_X 0x0100 /* X axis is inverted */
-#define KOS_IMG_INVERTED_Y 0x0200 /* Y axis is inverted */
-#define KOS_IMG_NOT_OWNER 0x0400 /* We don't own the buffer containing
-the data (ROM or similar) */
-
-/* Util functions ****************************************************************/
-
-/* Free a kos_img_t which was created by an image loader; set struct_also to non-zero
- if you want it to free the struct itself as well. */
+/** @} */
+
+/** \defgroup kos_img_fmts Image format types
+
+ This is the list of platform-independent image types that can be used as the
+ lower-half of the fmt value for a kos_img_t.
+
+ @{
+*/
+/** \brief Undefined or uninitialized format. */
+#define KOS_IMG_FMT_NONE 0x00
+
+/** \brief 24-bpp interleaved R/G/B bytes. */
+#define KOS_IMG_FMT_RGB888 0x01
+
+/** \brief 32-bpp interleaved A/R/G/B bytes. */
+#define KOS_IMG_FMT_ARGB8888 0x02
+
+/** \brief 16-bpp interleaved R (5 bits), G (6 bits), B (5 bits). */
+#define KOS_IMG_FMT_RGB565 0x03
+
+/** \brief 16-bpp interleaved A/R/G/B (4 bits each). */
+#define KOS_IMG_FMT_ARGB4444 0x04
+
+/** \brief 16-bpp interleaved A (1 bit), R (5 bits), G (5 bits), B (5 bits).
+ \note This can also be used for RGB555 (with the top bit ignored). */
+#define KOS_IMG_FMT_ARGB1555 0x05
+
+/** \brief Paletted, 4 bits per pixel (16 colors). */
+#define KOS_IMG_FMT_PAL4BPP 0x06
+
+/** \brief Paletted, 8 bits per pixel (256 colors). */
+#define KOS_IMG_FMT_PAL8BPP 0x07
+
+/** \brief 8-bit Y (4 bits), U (2 bits), V (2 bits). */
+#define KOS_IMG_FMT_YUV422 0x08
+
+/** \brief 15-bpp interleaved B (5 bits), G (6 bits), R (5 bits). */
+#define KOS_IMG_FMT_BGR565 0x09
+
+/** \brief 32-bpp interleaved R/G/B/A bytes. */
+#define KOS_IMG_FMT_RGBA8888 0x10
+
+/** \brief Basic format mask (not an actual format value). */
+#define KOS_IMG_FMT_MASK 0xff
+
+/** \brief X axis of image data is inverted (stored right to left). */
+#define KOS_IMG_INVERTED_X 0x0100
+
+/** \brief Y axis of image data is inverted (stored bottom to top). */
+#define KOS_IMG_INVERTED_Y 0x0200
+
+/** \brief The image is not the owner of the image data buffer.
+
+ This generally implies that the image data is stored in ROM and thus cannot
+ be freed.
+*/
+#define KOS_IMG_NOT_OWNER 0x0400
+
+/** @} */
+
+/** \brief Free a kos_img_t object.
+
+ This function frees the data in a kos_img_t object, returning any memory to
+ the heap as appropriate. Optionally, this can also free the object itself,
+ if required.
+
+ \param img The image object to free.
+ \param struct_also Set to non-zero to free the image object itself,
+ as well as any data contained therein.
+*/
void kos_img_free(kos_img_t *img, int struct_also);
__END_DECLS
diff --git a/addons/include/kos/md5.h b/addons/include/kos/md5.h
index 8afacf9..8901cc1 100644
--- a/addons/include/kos/md5.h
+++ b/addons/include/kos/md5.h
@@ -7,19 +7,67 @@
#ifndef __KOS_MD5_H
#define __KOS_MD5_H
+/** \file kos/md5.h
+ \brief Message Digest 5 (MD5) hashing support.
+
+ This file provides the functionality to compute MD5 hashes over any data
+ buffer. While MD5 isn't considered a safe cryptographic hash any more, it
+ still has its uses.
+
+ \author Lawrence Sebald
+*/
+
#include <sys/cdefs.h>
__BEGIN_DECLS
#include <arch/types.h>
+/** \brief MD5 context.
+
+ This structure contains the variables needed to maintain the internal state
+ of the MD5 code. You should not manipulate these variables manually, but
+ rather use the kos_md5_* functions to do everything you need.
+
+ \headerfile kos/md5.h
+*/
typedef struct kos_md5_cxt {
- uint64 size;
- uint32 hash[4];
- uint8 buf[64];
+ uint64 size; /**< \brief Size of the data in buf. */
+ uint32 hash[4]; /**< \brief Intermediate hash value. */
+ uint8 buf[64]; /**< \brief Temporary storage of values to be hashed. */
} kos_md5_cxt_t;
+/** \brief Initialize a MD5 context.
+
+ This function initializes the context passed in to the initial state needed
+ for computing a MD5 hash. You must call this function to initialize the
+ state variables before attempting to hash any blocks of data.
+
+ \param cxt The MD5 context to initialize.
+*/
void kos_md5_start(kos_md5_cxt_t *cxt);
+
+/** \brief Hash a block of data with MD5.
+
+ This function is used to hash the block of data input into the function with
+ MD5, updating the state context as appropriate. If the data does not fill an
+ entire block of 64-bytes (or there is left-over data), it will be stored in
+ the context for hashing with a future block. Thus, do not attempt to read
+ the intermediate hash value, as it will not be complete.
+
+ \param cxt The MD5 context to use.
+ \param input The block of data to hash.
+ \param size The number of bytes of input data passed in.
+*/
void kos_md5_hash_block(kos_md5_cxt_t *cxt, const uint8 *input, uint32 size);
+
+/** \brief Complete a MD5 hash.
+
+ This function computes the final MD5 hash of the context passed in,
+ returning the completed digest in the output parameter.
+
+ \param cxt The MD5 context to finalize.
+ \param output Where to store the final digest.
+*/
void kos_md5_finish(kos_md5_cxt_t *cxt, uint8 output[16]);
__END_DECLS
diff --git a/addons/include/kos/netcfg.h b/addons/include/kos/netcfg.h
index 75e875b..659a2ae 100644
--- a/addons/include/kos/netcfg.h
+++ b/addons/include/kos/netcfg.h
@@ -1,62 +1,153 @@
/* KallistiOS ##version##
kos/netcfg.h
- Copyright (C)2003 Dan Potter
+ Copyright (C) 2003 Dan Potter
*/
#ifndef __KOS_NETCFG_H
#define __KOS_NETCFG_H
+/** \file kos/netcfg.h
+ \brief Network configuration interface.
+
+ This file provides a common interface for reading and writing the network
+ configuration on KOS. The interface can read from the flashrom on the
+ Dreamcast or from a file (such as on a VMU or the like), and can write data
+ back to a file.
+
+ The data that is written out by this code is written in a relatively easy to
+ parse text-based format.
+
+ \author Dan Potter
+*/
+
#include <sys/cdefs.h>
__BEGIN_DECLS
#include <arch/types.h>
-/* Network configuration info. This holds the information about how we
- will start the networking and what settings to use. */
-#define NETCFG_METHOD_DHCP 0
-#define NETCFG_METHOD_STATIC 1
-#define NETCFG_METHOD_PPPOE 4
-#define NETCFG_SRC_VMU 0
-#define NETCFG_SRC_FLASH 1
-#define NETCFG_SRC_CWD 2
-#define NETCFG_SRC_CDROOT 3
+/** \defgroup netcfg_methods Network connection methods
+
+ These constants give the list of network connection methods that are
+ supported by the netcfg_t type. One of these will be in the method field of
+ objects of that type.
+
+ @{
+*/
+#define NETCFG_METHOD_DHCP 0 /**< \brief Use DHCP to configure. */
+#define NETCFG_METHOD_STATIC 1 /**< \brief Static network configuration. */
+#define NETCFG_METHOD_PPPOE 4 /**< \brief Use PPPoE. */
+/** @} */
+
+/** \defgroup netcfg_srcs Network configuration sources
+
+ These constants give the list of places that the network configuration might
+ be read from. One of these constants should be in the src field of objects
+ of type netcfg_t.
+
+ @{
+*/
+#define NETCFG_SRC_VMU 0 /**< \brief Read from a VMU. */
+#define NETCFG_SRC_FLASH 1 /**< \brief Read from the flashrom. */
+#define NETCFG_SRC_CWD 2 /**< \brief Read from the working directory. */
+#define NETCFG_SRC_CDROOT 3 /**< \brief Read from the root of the CD. */
+/** @} */
+
+/** \brief Network configuration information.
+
+ This structure contains information about the network configuration of the
+ system, as set up by the user.
+
+ \headerfile kos/netcfg.h
+*/
typedef struct netcfg {
- int src; // Config source
- int method; // Configuration method
- uint32 ip; // IP addresses
- uint32 gateway;
- uint32 netmask;
- uint32 broadcast;
- uint32 dns[2]; // DNS servers
- char hostname[64]; // DHCP hostname
- char email[64]; // E-Mail address
- char smtp[64]; // SMTP server
- char pop3[64]; // POP3 server
- char pop3_login[64]; // POP3 login name
- char pop3_passwd[64]; // POP3 password
- char proxy_host[64]; // Proxy server hostname
- int proxy_port; // Proxy server port
- char ppp_login[64]; // PPP login
- char ppp_passwd[64]; // PPP password
- char driver[64]; // Driver program filename (if any)
+ /** \brief Where was this configuration read from?
+ \see netcfg_srcs
+ */
+ int src;
+
+ /** \brief How should the network be configured?
+ \see netcfg_methods
+ */
+ int method;
+
+ uint32 ip; /**< \brief IPv4 address of the console */
+ uint32 gateway; /**< \brief IPv4 address of the gateway/router. */
+ uint32 netmask; /**< \brief Network mask for the local net. */
+ uint32 broadcast; /**< \brief Broadcast address for the local net. */
+ uint32 dns[2]; /**< \brief IPv4 address of the DNS servers. */
+ char hostname[64]; /**< \brief DNS/DHCP hostname. */
+ char email[64]; /**< \brief E-Mail address. */
+ char smtp[64]; /**< \brief SMTP server address. */
+ char pop3[64]; /**< \brief POP3 server address. */
+ char pop3_login[64]; /**< \brief POP3 server username. */
+ char pop3_passwd[64]; /**< \brief POP3 server password. */
+ char proxy_host[64]; /**< \brief Proxy server address. */
+ int proxy_port; /**< \brief Proxy server port. */
+ char ppp_login[64]; /**< \brief PPP Username. */
+ char ppp_passwd[64]; /**< \brief PPP Password. */
...<truncated>...
hooks/post-receive
--
A pseudo Operating System for the Dreamcast.
|
