[tuxdroid-svn] r665 - daemon/trunk/libs firmware/tuxaudio/trunk firmware/tuxcore/trunk firmware/tux
Status: Beta
Brought to you by:
ks156
From: jaguarondi <c2m...@c2...> - 2007-11-08 14:19:31
|
Author: jaguarondi Date: 2007-11-08 15:19:22 +0100 (Thu, 08 Nov 2007) New Revision: 665 Added: firmware/tuxdefs/api.h firmware/tuxdefs/defines.h Modified: daemon/trunk/libs/USBDaemon_status_table.c daemon/trunk/libs/USBDaemon_status_table.h firmware/tuxaudio/trunk/main.c firmware/tuxcore/trunk/global.h firmware/tuxdefs/commands.h firmware/tuxup/trunk/main.c Log: * Updated Doxygen comments of the firmware api (commands.h). * Reorganized commands.h, now split into api.h and defines.h. This is a work in progress, commands.h will be removed once all elements have been documented and moved to the right header file. Updated the daemon, tuxup, tuxcore and tuxaudio accordingly. Hope they still work. Modified: daemon/trunk/libs/USBDaemon_status_table.c =================================================================== --- daemon/trunk/libs/USBDaemon_status_table.c 2007-11-08 09:50:57 UTC (rev 664) +++ daemon/trunk/libs/USBDaemon_status_table.c 2007-11-08 14:19:22 UTC (rev 665) @@ -28,6 +28,7 @@ #include "USBDaemon_log.h" #include "USBDaemon_tcp_server.h" #include "../tuxdefs/commands.h" +#include "../tuxdefs/defines.h" /*_____________________ V A R I A B L E S __________________________________*/ _PORT_BYTE_ portb; Modified: daemon/trunk/libs/USBDaemon_status_table.h =================================================================== --- daemon/trunk/libs/USBDaemon_status_table.h 2007-11-08 09:50:57 UTC (rev 664) +++ daemon/trunk/libs/USBDaemon_status_table.h 2007-11-08 14:19:22 UTC (rev 665) @@ -24,7 +24,7 @@ #define __USBDAEMON_STATUS_TABLE_H__ /*_____________________ I N C L U D E S____________________________________ */ -#include "../tuxdefs/commands.h" +#include "../tuxdefs/api.h" #include <stdbool.h> /*_____________________ D E F I N E S ______________________________________*/ @@ -269,11 +269,6 @@ extern unsigned char cmd_status_flag; extern unsigned char pong_received; -extern version_t hw_version[4]; -extern revision_t hw_revision[4]; -extern author_t hw_author[4]; -extern unsigned char sound_flash_count; - /** * Tux status table. * Modified: firmware/tuxaudio/trunk/main.c =================================================================== --- firmware/tuxaudio/trunk/main.c 2007-11-08 09:50:57 UTC (rev 664) +++ firmware/tuxaudio/trunk/main.c 2007-11-08 14:19:22 UTC (rev 665) @@ -25,6 +25,7 @@ #include <util/delay.h> #include <avr/sleep.h> +#include "common/defines.h" #include "init.h" #include "varis.h" #include "spi.h" Modified: firmware/tuxcore/trunk/global.h =================================================================== --- firmware/tuxcore/trunk/global.h 2007-11-08 09:50:57 UTC (rev 664) +++ firmware/tuxcore/trunk/global.h 2007-11-08 14:19:22 UTC (rev 665) @@ -28,6 +28,8 @@ #include <avr/io.h> #include "common/commands.h" +#include "common/defines.h" +#include "common/api.h" /* * Custom types Added: firmware/tuxdefs/api.h =================================================================== --- firmware/tuxdefs/api.h (rev 0) +++ firmware/tuxdefs/api.h 2007-11-08 14:19:22 UTC (rev 665) @@ -0,0 +1,192 @@ +/* + * TUXDEFS - Common defines used by the firmware and daemon of tuxdroid + * Copyright (C) 2007 C2ME S.A. <tux...@c2...> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + +/* $Id$*/ + +/** \file api.h + \brief Firmware API + \ingroup api +*/ + +/** \defgroup api Firmware API + + These firmware commands constitute the program interface between all CPUs + and the computer. Both actions (also called commands) and status are + controlled by these commands. + */ +/*! @{ */ + +#ifndef _API_H_ +#define _API_H_ + +#include <stdint.h> + +/* + * COMMANDS + * + * Commands are divided in 4 groups depending on the number of parameters they + * have: + * - 0b00xxxxxx (0x00-0x3F) for void functions + * - 0b01xxxxxx (0x40-0x7F) for functions requesting 1 parameter + * - 0b10xxxxxx (0x80-0xBF) for functions requesting 2 parameters + * - 0b11xxxxxx (0xC0-0xFF) for functions requesting 3 parameters + * + * The same definition of commands are used for all communications between the + * computer and Tux. But depending on the communication way, the set of + * commands will differ. There will be 3 sets based on Tux's architecture: + * Tux's commands, audio commands, and status. + * + * 1. Tux's commands are sent from the computer to Tux in order to control all + * actuators: motors, LEDs, IR, etc. They can have any number of parameters + * (from 0 to 3) and are defined in "Tux's core API"; + * + * 2. Audio commands are sent from the computer or from Tux to the audio chip. + * They never have 3 parameters; + * + * 3. Status are sent from Tux back to the computer in order to give feedback + * on sensor states or send some received IR code. + * + * Note: Audio commands are sent from the computer or from Tux to the audio + * chip. The audio chip also receives status which it transfers to the + * computer. In order to differentiate status from audio commands easily, we + * chose to have audio commands <0xC0 which means they can have 0, 1 or 2 + * parameters but not 3. Status commands will always have 3 parameters has we + * always want to send as much information as possible anyway. + * + * \todo TODO this is still relevant but should be clarified, use this filed to + * explain the api on a higher level. The command flow through all CPUs need to + * be reviewed prior to update this. + */ + +/** + * \name Request general information + * These commands request some general information of the CPUs and their + * firmware. This includes identifiers, versions, revisions, author, etc. + * @{ */ + +/** Request generic informations from tuxcore. */ +#define INFO_TUXCORE_CMD 0x02 +/** Request generic informations from tuxcaudio. */ +#define INFO_TUXAUDIO_CMD 0x03 +/** Request generic informations from tuxrf. */ +#define INFO_TUXRF_CMD 0x04 +/** Request generic informations from fuxrf. */ +#define INFO_FUXRF_CMD 0x05 +/** Request generic informations from fuxusb. */ +#define INFO_FUXUSB_CMD 0x06 + +/*! @} */ + +/** + * \name Return general information + * These commands return some general information of the CPUs and their + * firmware. This includes identifiers, versions, revisions, author, etc. + * + * Only the version command includes the CPU identifier. This command should + * then be sent first so that the daemon knows which CPU is sending all their + * information commands. + * @{ */ +/** + * \page versioning Versioning + * + * Tuxdroid is made of 5 CPUs having each their own firmware. Releasing a new + * tuxdroid firmware only makes sense in releasing all 5 firmware as there's a + * lot of interactions between them. + * + * We then have 5 firmware version numbers and added a 6th version number for + * the package that will group all 5 firmware. This package will be called the + * firmware release. + * + * In order to keep all numbers coherent, we decided to follow these rules when + * releasing a new set of firmware: + * - all major and minor numbers should be equal; + * - the higher update number of all CPUs will be the update number of the + * release package; + * - when increasing the update number, use the highest update number among all + * CPUs + 1. + */ +/** + * Return the CPU number and the firmware version in major.minor.update + * format. + * + * In the current implementation, each firmware simply fetches the version_t + * structure. + * + * Parameters: + * - 1 - 3 lower bits are the CPU number, + * 5 higher bits are the major version number. + * - 2 - minor version number. + * - 3 - update version number. + */ +#define VERSION_CMD 0xC8 + +/** + * Return the firmware revision number. + * + * In the current implementation, each firmware simply fetches the revision_t + * structure. + * As the AVR is little-endian, the 16 bits revision is sent with the LSB + * first. + * + * Parameters: + * - 1 - LSB of the revision number. + * - 2 - MSB of the revision number. + * - 3 - undefined. + */ +#define REVISION_CMD 0xC9 + +/** + * Return the firmware author information. + * + * In the current implementation, each firmware simply fetches the author_t + * structure. + * As the AVR is little-endian, the 16 bits author number is sent with the LSB + * first. + * + * The author id can be used to differentiate official firmware from other + * custom versions. + * The variation number can be used by one author to differentiate multiple + * variations of a firmware. This is useful if someone develops a couple of + * firmware that would require specific external sensors for example, or . + * firmware that implements some functions differently like the flash usage, or + * driving the motors another way. + * + * Official firmware from Kysoh has the author id '0'. If you're developing + * firmware, use another number. + * + * Parameters: + * - 1 - LSB of the author id. + * - 2 - MSB of the author id. + * - 3 - variation number. + */ +#define AUTHOR_CMD 0xCA + +/** + * Return the sound flash information. + * + * Parameters: + * - 1 - number of sounds stored in the flash. + */ +#define SOUND_VAR_CMD 0xCB + +/*! @} */ + +/*! @} */ +#endif /* _API_H_ */ + Property changes on: firmware/tuxdefs/api.h ___________________________________________________________________ Name: svn:mime-type + text/plain Name: svn:keywords + Id Name: svn:eol-style + native Modified: firmware/tuxdefs/commands.h =================================================================== --- firmware/tuxdefs/commands.h 2007-11-08 09:50:57 UTC (rev 664) +++ firmware/tuxdefs/commands.h 2007-11-08 14:19:22 UTC (rev 665) @@ -24,7 +24,7 @@ \ingroup commands */ -/** \defgroup commands Firmware API +/** \defgroup commands Firmware interface (DEPRECATED) These firmware commands constitute the program interface between all CPUs and the computer. Both actions (also called commands) and status are @@ -35,221 +35,7 @@ #define _COMMAND_H_ #include <stdint.h> - -/** - * \name Request information - * These commands request some general information of the CPUs and their - * firmware. This includes identifiers, versions, revisions, author, etc. - * @{ */ -/** - * \brief CPU identifiers - */ -enum CPU_IDENTIFIERS -{ - /** 'tuxcore' is the core CPU of tuxdroid, it manages the sensors and - * actuators. */ - TUXCORE_CPU_NUM = 0, - /** 'tuxaudio' is the CPU of tuxdroid that handles audio (microphone, - * speaker and the audio flash) and communications between the RF and - * tuxcore. */ - TUXAUDIO_CPU_NUM = 1, - /** 'tuxrf' is the RF CPU of tuxdroid. */ - TUXRF_CPU_NUM = 2, - /** 'fuxrf' is the RF CPU inside the dongle. */ - FUXRF_CPU_NUM = 3, - /** 'fuxusb' is the USB CPU inside the dongle. */ - FUXUSB_CPU_NUM = 4, -}; - -/** - * /brief I2C addresses of all CPUs - * - * tuxcore, tuxaudio, tuxrf and fuxrf have different I2C addresses when they're - * running in normal or bootloader mode. - */ -enum I2C_ADDRESSES -{ - TUXCORE_BL_ADDR = 0X30, - TUXAUDIO_BL_ADDR = 0X31, - TUXRF_BL_ADDR = 0X32, - FUXRF_BL_ADDR = 0X33, - /* XXX we should remove these TWAR stuff from here */ - TUXCORE_BL_TWAR = (TUXCORE_BL_ADDR << 1), - TUXAUDIO_BL_TWAR = (TUXAUDIO_BL_ADDR << 1), - TUXRF_BL_TWAR = (TUXRF_BL_ADDR << 1), - FUXRF_BL_TWAR = (FUXRF_BL_ADDR << 1), -}; - /* - * COMMANDS - * - * Commands are divided in 4 groups depending on the number of parameters they - * have: - * - 0b00xxxxxx (0x00-0x3F) for void functions - * - 0b01xxxxxx (0x40-0x7F) for functions requesting 1 parameter - * - 0b10xxxxxx (0x80-0xBF) for functions requesting 2 parameters - * - 0b11xxxxxx (0xC0-0xFF) for functions requesting 3 parameters - * - * The same definition of commands are used for all communications between the - * computer and Tux. But depending on the communication way, the set of - * commands will differ. There will be 3 sets based on Tux's architecture: - * Tux's commands, audio commands, and status. - * - * 1. Tux's commands are sent from the computer to Tux in order to control all - * actuators: motors, LEDs, IR, etc. They can have any number of parameters - * (from 0 to 3) and are defined in "Tux's core API"; - * - * 2. Audio commands are sent from the computer or from Tux to the audio chip. - * They never have 3 parameters; - * - * 3. Status are sent from Tux back to the computer in order to give feedback - * on sensor states or send some received IR code. - * - * Note: Audio commands are sent from the computer or from Tux to the audio - * chip. The audio chip also receives status which it transfers to the - * computer. In order to differentiate status from audio commands easily, we - * chose to have audio commands <0xC0 which means they can have 0, 1 or 2 - * parameters but not 3. Status commands will always have 3 parameters has we - * always want to send as much information as possible anyway. - * - * /todo TODO this is still relevant but should be clarified - */ - - -/* - * Version commands - */ -/** Request generic informations from tuxcore. */ -#define INFO_TUXCORE_CMD 0x02 -/** Request generic informations from tuxcaudio. */ -#define INFO_TUXAUDIO_CMD 0x03 -/** Request generic informations from tuxrf. */ -#define INFO_TUXRF_CMD 0x04 -/** Request generic informations from fuxrf. */ -#define INFO_FUXRF_CMD 0x05 -/** Request generic informations from fuxusb. */ -#define INFO_FUXUSB_CMD 0x06 - -/** - * Return the CPU number and the firmware version in major.minor.update - * format. - * - * In the current implementation, each firmware simply fetches the version_t - * structure. - */ -#define VERSION_CMD 0xC8 - -/** - * Version structure (DEPRECATED) - * This version_bf_t type can't be used to send the bytes over a channel as the - * order of the bits in the bit field may be freely rearranged by GCC. - * - * /todo TODO check that no firmware is using this anymore and delete this. - */ -typedef struct -{ - uint8_t version_cmd; - uint8_t cpu_nbr:3; /* 3 lower bits are the CPU number */ - uint8_t ver_major:5; /* 5 higher bits are the major version number */ - uint8_t ver_minor; - uint8_t ver_update; -} version_bf_t; - -/** - * Version structure that holds the raw data that will be sent when the - * VERSION_CMD is received. - * - * This version_t type should be used to send the bytes over a channel such as - * USB or TCP-IP. Use the macros to set or retrieve values of the cpu_ver_maj - * byte. - */ -typedef struct -{ - uint8_t version_cmd; - uint8_t cpu_ver_maj; /** 3 lower bits are the CPU number, 5 higher bits are - the major version number */ - uint8_t ver_minor; - uint8_t ver_update; -} version_t; - -/** Concatenate the CPU number and the major version number to create - * 'cpu_ver_maj'. - * /param[cpu_nbr] CPU number - * /param[ver_major] major version number - * /return true if successful, false otherwise */ -#define CPU_VER_JOIN(cpu_nbr, ver_major) ((cpu_nbr & 0x7) + (ver_major << 3)) -/** Retrieve the CPU number from 'cpu_ver_maj'. */ -#define CPU_VER_CPU(cpu_ver_maj) (cpu_ver_maj & 0x07) -/** Retrieve the major version number from 'cpu_ver_maj'. */ -#define CPU_VER_MAJ(cpu_ver_maj) ((cpu_ver_maj & 0xF8) >> 3) - -/** - * Return the firmware revision number. - * - * In the current implementation, each firmware simply fetches the revision_t - * structure. - * As the AVR is little-endian, the 16 bits revision is sent with the LSB - * first. - * - * 1st parameter: LSB of the revision number. - * 2nd parameter: MSB of the revision number. - * 3rd parameter: undefined. - */ -#define REVISION_CMD 0xC9 -/** - * Revision number of the firmware from the subversion repository. - */ -typedef struct -{ - uint8_t revision_cmd; - uint16_t revision; - uint8_t _undefined_; -} revision_t; - -/** - * Return the firmware author information. - * - * In the current implementation, each firmware simply fetches the author_t - * structure. - * As the AVR is little-endian, the 16 bits author number is sent with the LSB - * first. - * - * The author id can be used to differentiate official firmware from other - * custom versions. - * The variation number can be used by one author to differentiate multiple - * variations of a firmware. This is useful if someone develops a couple of - * firmware that would require specific external sensors for example, or . - * firmware that implements some functions differently like the flash usage, or - * driving the motors another way. - * - * Official firmware from Kysoh has the author id '0'. If you're developing - * firmware, use another number. - * - * 1st parameter: LSB of the author id. - * 2nd parameter: MSB of the author id. - * 3rd parameter: variation number. - */ -#define AUTHOR_CMD 0xCA -/** - * Author information of the firmware. - */ -typedef struct -{ - uint8_t author_cmd; - uint16_t author_id; - uint8_t variation; -} author_t; - -/** - * Return the sound flash information. - * - * 1st parameter: number of sounds stored in the flash. - */ -#define SOUND_VAR_CMD 0xCB - -/*! @} */ - -/* * Move commands */ Added: firmware/tuxdefs/defines.h =================================================================== --- firmware/tuxdefs/defines.h (rev 0) +++ firmware/tuxdefs/defines.h 2007-11-08 14:19:22 UTC (rev 665) @@ -0,0 +1,152 @@ +/* + * TUXDEFS - Common defines used by the firmware and daemon of tuxdroid + * Copyright (C) 2007 C2ME S.A. <tux...@c2...> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + +/* $Id$*/ + +/** \file defines.h + \brief Common firmware constants, structures and types. + + \ingroup common +*/ + +/** \defgroup common Common firmware constants, structures and types. + */ +/*! @{ */ + +#ifndef _DEFINES_H_ +#define _DEFINES_H_ + +/** + * \name Identifiers and addresses. + * @{ */ +/** + * CPU identifiers. + */ +enum CPU_IDENTIFIERS +{ + /** 'tuxcore' is the core CPU of tuxdroid, it manages the sensors and + * actuators. */ + TUXCORE_CPU_NUM = 0, + /** 'tuxaudio' is the CPU of tuxdroid that handles audio (microphone, + * speaker and the audio flash) and communications between the RF and + * tuxcore. */ + TUXAUDIO_CPU_NUM = 1, + /** 'tuxrf' is the RF CPU of tuxdroid. */ + TUXRF_CPU_NUM = 2, + /** 'fuxrf' is the RF CPU inside the dongle. */ + FUXRF_CPU_NUM = 3, + /** 'fuxusb' is the USB CPU inside the dongle. */ + FUXUSB_CPU_NUM = 4, +}; + +/** + * I2C addresses of all CPUs. + * + * tuxcore, tuxaudio, tuxrf and fuxrf have different I2C addresses when they're + * running in normal or bootloader mode. + */ +enum I2C_ADDRESSES +{ + TUXCORE_BL_ADDR = 0X30, + TUXAUDIO_BL_ADDR = 0X31, + TUXRF_BL_ADDR = 0X32, + FUXRF_BL_ADDR = 0X33, + /* XXX we should remove these TWAR stuff from here */ + TUXCORE_BL_TWAR = (TUXCORE_BL_ADDR << 1), + TUXAUDIO_BL_TWAR = (TUXAUDIO_BL_ADDR << 1), + TUXRF_BL_TWAR = (TUXRF_BL_ADDR << 1), + FUXRF_BL_TWAR = (FUXRF_BL_ADDR << 1), +}; + +/*! @} */ + +/** + * \name Versioning + */ +/*! @{ */ +/** + * Version structure (DEPRECATED). + * This version_bf_t type can't be used to send the bytes over a channel as the + * order of the bits in the bit field may be freely rearranged by GCC. + * + * \todo TODO check that no firmware is using this anymore and delete this. + */ +typedef struct +{ + uint8_t version_cmd; + uint8_t cpu_nbr:3; /**< 3 lower bits are the CPU number */ + uint8_t ver_major:5; /**< 5 higher bits are the major version number */ + uint8_t ver_minor; + uint8_t ver_update; +} version_bf_t; + +/** + * Version structure that holds the raw data that will be sent when the + * VERSION_CMD is received. + * + * This version_t type should be used to send the bytes over a channel such as + * USB or TCP-IP. Use the macros to set or retrieve values of the cpu_ver_maj + * byte. + */ +typedef struct +{ + uint8_t version_cmd; + uint8_t cpu_ver_maj; /** 3 lower bits are the CPU number, 5 higher bits are + the major version number */ + uint8_t ver_minor; + uint8_t ver_update; +} version_t; + +/** Concatenate the CPU number and the major version number to create + * 'cpu_ver_maj'. + * \param cpu_nbr CPU number. + * \param ver_major major version number. + * \return cpu_ver_maj byte.*/ +#define CPU_VER_JOIN(cpu_nbr, ver_major) ((cpu_nbr & 0x7) + (ver_major << 3)) +/** Return the CPU number from 'cpu_ver_maj'. */ +#define CPU_VER_CPU(cpu_ver_maj) (cpu_ver_maj & 0x07) +/** Return the major version number from 'cpu_ver_maj'. */ +#define CPU_VER_MAJ(cpu_ver_maj) ((cpu_ver_maj & 0xF8) >> 3) + +/** + * Revision number of the firmware from the subversion repository. + */ +typedef struct +{ + uint8_t revision_cmd; + uint16_t revision; + uint8_t _undefined_; +} revision_t; + +/** + * Author information of the firmware. + */ +typedef struct +{ + uint8_t author_cmd; + uint16_t author_id; + uint8_t variation; +} author_t; + +/*! @} */ + +/*! @} */ + +#endif /* _DEFINES_H_ */ + Property changes on: firmware/tuxdefs/defines.h ___________________________________________________________________ Name: svn:mime-type + text/plain Name: svn:keywords + Id Name: svn:eol-style + native Modified: firmware/tuxup/trunk/main.c =================================================================== --- firmware/tuxup/trunk/main.c 2007-11-08 09:50:57 UTC (rev 664) +++ firmware/tuxup/trunk/main.c 2007-11-08 14:19:22 UTC (rev 665) @@ -29,7 +29,7 @@ #include "usb-connection.h" #include "bootloader.h" #include "version.h" -#include "common/commands.h" +#include "common/defines.h" /* Messages. */ static const char *msg_old_firmware = |