Merge pull request #232 from ut-issl/feature/fix_ph

CTCP分離とSpacePacket実装に伴う，PHの微修正とPLのコメント修正

TlmCmd/packet_handler.c

@@ -1,8 +1,12 @@
 #pragma section REPRO
+/**
+ * @file
+ * @brief C2A 全体を流れる Common Packet の配送を制御する
+ */
 #include "packet_handler.h"
 
-#include <stddef.h> // for NULL
-#include <string.h> // for memcpy
+#include <stddef.h>
+#include <string.h>
 
 #include "../System/TimeManager/time_manager.h"
 #include "command_analyze.h"
@@ -40,8 +44,8 @@ static PH_ACK PH_analyze_block_cmd_(const CommonCmdPacket* packet);
 static PH_ACK PH_add_gs_cmd_(const CommonCmdPacket* packet);
 static PH_ACK PH_add_rt_cmd_(const CommonCmdPacket* packet);
 static PH_ACK PH_add_tl_cmd_(int line_no,
-                            const CommonCmdPacket* packet,
-                            cycle_t now);
+                             const CommonCmdPacket* packet,
+                             cycle_t now);
 /**
  * @brief UTL_cmd を TL_cmd に変換して tl_cmd_list に追加する
  * @note TODO：const cast でもいいか検討する
@@ -53,6 +57,7 @@ static PH_ACK PH_add_ms_tlm_(const CommonTlmPacket* packet);
 static PH_ACK PH_add_st_tlm_(const CommonTlmPacket* packet);
 static PH_ACK PH_add_rp_tlm_(const CommonTlmPacket* packet);
 
+
 void PH_init(void)
 {
   PL_initialize_with_ccp(PH_gs_cmd_stock_, PH_gs_cmd_ccp_stock_, PH_GS_CMD_LIST_MAX, &PH_gs_cmd_list);
@@ -69,10 +74,7 @@ void PH_init(void)
   PH_user_init();
 }
 
-// パケット解析関数
-// GSTOSからのパケット以外もすべてここで処理される
-// Cmd_GENERATE_TLMとかも．
-// FIXME: 外の OBC からコマンドが飛んでくることもあるので，長さが足りているかのチェックを入れる！ PH_analyze_tlm_packet, PH_analyze_cmd_packet でも
+
 PH_ACK PH_analyze_packet(const CommonTlmCmdPacket* packet)
 {
   if (packet == NULL) return PH_UNKNOWN;    // FIXME: 返り値変えたい
@@ -94,11 +96,11 @@ PH_ACK PH_analyze_packet(const CommonTlmCmdPacket* packet)
   return PH_UNKNOWN;
 }
 
+
 PH_ACK PH_analyze_cmd_packet(const CommonCmdPacket* packet)
 {
   PH_ACK ack;
-  // FIXME: CommonCmdPacket としての妥当性チェックを入れる！！！
-  if (packet == NULL) return PH_UNKNOWN;    // FIXME: 返り値変えたい
+  if (!CCP_is_valid_packet(packet)) return PH_UNKNOWN;    // FIXME: 返り値変えたい
 
   // ユーザー定義部
   // 基本的には，接続されているC2Aを搭載したボードに
@@ -137,6 +139,7 @@ PH_ACK PH_analyze_cmd_packet(const CommonCmdPacket* packet)
   }
 }
 
+
 static PH_ACK PH_analyze_block_cmd_(const CommonCmdPacket* packet)
 {
   switch (BCT_register_cmd(packet))
@@ -161,11 +164,11 @@ static PH_ACK PH_analyze_block_cmd_(const CommonCmdPacket* packet)
   }
 }
 
+
 PH_ACK PH_analyze_tlm_packet(const CommonTlmPacket* packet)
 {
   ctp_dest_flags_t flags;
-  // FIXME: CommonTlmPacket としての妥当性チェックを入れる！！！
-  if (packet == NULL) return PH_UNKNOWN;    // FIXME: 返り値変えたい
+  if (!CTP_is_valid_packet(packet)) return PH_UNKNOWN;    // FIXME: 返り値変えたい
 
   flags = CTP_get_dest_flags(packet);
 
@@ -187,16 +190,10 @@ PH_ACK PH_analyze_tlm_packet(const CommonTlmPacket* packet)
   return PH_SUCCESS;
 }
 
+
 CCP_EXEC_STS PH_dispatch_command(const CommonCmdPacket* packet)
 {
-  if (packet == NULL) return CCP_EXEC_UNKNOWN;    // FIXME: 返り値変えたい
-
-  // FIXME: CTCP, SpacePacket 整理で直す
-  // if (CTCP_get_packet_type(packet) != CTCP_PACKET_TYPE_CMD)
-  // {
-  //   // CMD以外のパケットが来たら異常判定。
-  //   return CCP_EXEC_PACKET_FMT_ERR;
-  // }
+  if (!CCP_is_valid_packet(packet)) return CCP_EXEC_UNKNOWN;    // FIXME: 返り値変えたい
 
   // FIXME: CTCP, SpacePacket 整理で直す
   if (CCP_get_apid(packet) == CCP_APID_TO_ME)
@@ -207,10 +204,11 @@ CCP_EXEC_STS PH_dispatch_command(const CommonCmdPacket* packet)
   else
   {
     // 別機器宛コマンドの場合はパケット分配処理へ
-    return PH_user_cmd_router(packet);              // 当初，coreにcmd_router_が存在したが，coreにあっても意味がないのでuserのみにした
+    return PH_user_cmd_router(packet);
   }
 }
 
+
 static PH_ACK PH_add_gs_cmd_(const CommonCmdPacket* packet)
 {
   PL_ACK ack = PL_push_back(&PH_gs_cmd_list, packet);
@@ -220,6 +218,7 @@ static PH_ACK PH_add_gs_cmd_(const CommonCmdPacket* packet)
   return PH_SUCCESS;
 }
 
+
 static PH_ACK PH_add_rt_cmd_(const CommonCmdPacket* packet)
 {
   PL_ACK ack = PL_push_back(&PH_rt_cmd_list, packet);
@@ -229,6 +228,7 @@ static PH_ACK PH_add_rt_cmd_(const CommonCmdPacket* packet)
   return PH_REGISTERED;
 }
 
+
 static PH_ACK PH_add_tl_cmd_(int line_no,
                             const CommonCmdPacket* packet,
                             cycle_t now)
@@ -254,6 +254,7 @@ static PH_ACK PH_add_tl_cmd_(int line_no,
   }
 }
 
+
 static PH_ACK PH_add_utl_cmd_(const CommonCmdPacket* packet)
 {
   static CommonCmdPacket temp_; // サイズが大きいため静的領域に確保
@@ -271,6 +272,7 @@ static PH_ACK PH_add_utl_cmd_(const CommonCmdPacket* packet)
   return PH_add_tl_cmd_(0, &temp_, TMGR_get_master_total_cycle());
 }
 
+
 static PH_ACK PH_add_ms_tlm_(const CommonTlmPacket* packet)
 {
   PL_ACK ack = PL_push_back(&PH_ms_tlm_list, packet);
@@ -280,6 +282,7 @@ static PH_ACK PH_add_ms_tlm_(const CommonTlmPacket* packet)
   return PH_REGISTERED;
 }
 
+
 static PH_ACK PH_add_st_tlm_(const CommonTlmPacket* packet)
 {
   PL_ACK ack = PL_push_back(&PH_st_tlm_list, packet);
@@ -289,6 +292,7 @@ static PH_ACK PH_add_st_tlm_(const CommonTlmPacket* packet)
   return PH_REGISTERED;
 }
 
+
 static PH_ACK PH_add_rp_tlm_(const CommonTlmPacket* packet)
 {
   PL_ACK ack = PL_push_back(&PH_rp_tlm_list, packet);

TlmCmd/packet_handler.h

@@ -1,3 +1,7 @@
+/**
+ * @file
+ * @brief C2A 全体を流れる Common Packet の配送を制御する
+ */
 #ifndef PACKET_HANDLER_H_
 #define PACKET_HANDLER_H_
 
@@ -6,8 +10,7 @@
 
 #define PH_GS_CMD_LIST_MAX  (8)
 #define PH_RT_CMD_LIST_MAX  (32)
-#define PH_TL0_CMD_LIST_MAX (TL_TLM_PAGE_SIZE * TL_TLM_PAGE_MAX)   // コメント追加（2019/08/19）
-                                                                   // これが最長じゃないといけない
+#define PH_TL0_CMD_LIST_MAX (TL_TLM_PAGE_SIZE * TL_TLM_PAGE_MAX)   // これが最長じゃないといけない
                                                                    // TLCD_tl_list_for_tlmの長さがこれなので！！
 #define PH_TL1_CMD_LIST_MAX (TL_TLM_PAGE_SIZE * 4)
 #define PH_TL2_CMD_LIST_MAX (TL_TLM_PAGE_SIZE * 4)
@@ -55,18 +58,50 @@ typedef enum
 extern PacketList PH_gs_cmd_list;
 extern PacketList PH_rt_cmd_list;
 extern PacketList PH_tl_cmd_list[TL_ID_MAX];
-// extern PacketList PH_hk_tlm_list;    // EQUではMS TLMに統合
+// extern PacketList PH_hk_tlm_list;    // 現在は MS TLM に統合されている（ TODO: 今後また分離させても良いかも．要検討）
 extern PacketList PH_ms_tlm_list;
 extern PacketList PH_st_tlm_list;
 extern PacketList PH_rp_tlm_list;
 
+/**
+ * @brief Packet Handler を初期化
+ * @param  void
+ * @return void
+ */
 void PH_init(void);
 
-// FIXME: CTCP大改修がおわったらコメント入れる！
+/**
+ * @brief  CTCP を解析する
+ * @note   パケット解析とは，パケットを適切なキューにエンキューすることである（実行することではない）
+ * @note   Common Packet とは， GS から送られてくるものだけでなく，
+ *         C2A 内部で発行されるものや，他の OBC から送られてくるものなどもある
+ * @note   Cmd か Tlm かが確定している場合， PH_analyze_tlm_packet, PH_analyze_cmd_packet を用いる
+ * @param  packet: 解析するパケット
+ * @return PH_ACK
+ */
 PH_ACK PH_analyze_packet(const CommonTlmCmdPacket* packet);
+
+/**
+ * @brief  CTP を解析する
+ * @note   パケット解析とは，パケットを適切なキューにエンキューすることである（実行することではない）
+ * @param  packet: 解析するパケット
+ * @return PH_ACK
+ */
 PH_ACK PH_analyze_tlm_packet(const CommonTlmPacket* packet);
+
+/**
+ * @brief  CCP を解析する
+ * @note   パケット解析とは，パケットを適切なキューにエンキューすることである（実行することではない）
+ * @param  packet: 解析するパケット
+ * @return PH_ACK
+ */
 PH_ACK PH_analyze_cmd_packet(const CommonCmdPacket* packet);
 
+/**
+ * @brief  CCP をコマンドとして解釈して実行，ないしは別機器へ配送する
+ * @param  packet: 実行 or 配送するコマンドパケット
+ * @return CCP_EXEC_STS
+ */
 CCP_EXEC_STS PH_dispatch_command(const CommonCmdPacket* packet);
 
 #endif

TlmCmd/packet_list.c

@@ -14,15 +14,16 @@
 
 /**
  * @brief 未使用 Node を新規に取得
- * @param[in] pl: PacketList
+ * @note  取得されたものは使われることを想定（引数として与えられた pl の内部状態は更新される）
+ * @param[in,out] pl: PacketList
  * @retval 未使用 Node
  * @retval NULL （PacketListが満杯の時）
  */
 static PL_Node* PL_get_free_node_(PacketList* pl);
 
 /**
  * @brief 先頭 Node を落とす
- * @param[in] pl: PacketList
+ * @param[in,out] pl: PacketList
  * @retval PL_SUCCESS: 成功
  * @retval PL_LIST_EMPTY: PacketList が空
  */
@@ -385,7 +386,7 @@ PL_ACK PL_deploy_block_cmd(PacketList* pl, const bct_id_t block, cycle_t start_a
 }
 
 
-PL_ACK PL_check_tl_cmd(PacketList* pl, cycle_t time)
+PL_ACK PL_check_tl_cmd(const PacketList* pl, cycle_t time)
 {
   if (pl->packet_type_ != PL_PACKET_TYPE_CCP) return PL_PACKET_TYPE_ERR;
 

TlmCmd/packet_list.h

@@ -92,7 +92,7 @@ typedef struct
  * @param[in] node_num: PL_Node の数
  * @param[in] packet_type: 保持する packet の型情報．PL_PACKET_TYPE を参照
  * @param[in] packet_size: 使用する packet の型サイズ
- * @param[out] pl: 初期化する PacketList
+ * @param[in,out] pl: 初期化する PacketList
  * @retval PL_SUCCESS: 成功
  * @retval PL_PACKET_TYPE_ERR: 型関連エラー
  */
@@ -105,9 +105,8 @@ PL_ACK PL_initialize(PL_Node* pl_node_stock,
 
 /**
  * @brief PacketList をクリア
- * @param[in] pl: クリアする PacketList
- * @retval PL_SUCCESS: 成功
- * @retval PL_PACKET_TYPE_ERR: 型関連エラー
+ * @param[in,out] pl: クリアする PacketList
+ * @return void
  * @note 全 active Node を削除して 全て inactive の stock にする
  */
 void PL_clear_list(PacketList* pl);
@@ -239,7 +238,7 @@ PL_ACK PL_drop_node(PacketList* pl, PL_Node* prev, PL_Node* current);
 /**
  * @brief CCP が時系列に並ぶように CCP を挿入する
  * @note TimeLine だけでなく TaskList もこれを使い，その場合， now は step_t になることに注意
- * @param[in] pl: PacketList
+ * @param[in,out] pl: CCP を挿入する PacketList
  * @param[in] packet: 挿入する CCP
  * @param[in] now: 基準時刻 (TimeLine なら現在時刻， TaskList なら現在 step)
  * @retval PL_SUCCESS: 成功
@@ -254,7 +253,7 @@ PL_ACK PL_insert_tl_cmd(PacketList* pl, const CommonCmdPacket* packet, cycle_t n
 /**
  * @brief PacketList 上に BC を展開する
  * @note TimeLine だけでなく TaskList もこれを使い，その場合， start_at は step_t になることに注意
- * @param[in] pl: PacketList
+ * @param[in,out] pl: BC を展開する PacketList
  * @param[in] block: 展開する BC の ID
  * @param[in] start_at: 開始基準時刻
  * @retval PL_SUCCESS: 成功
@@ -275,6 +274,6 @@ PL_ACK PL_deploy_block_cmd(PacketList* pl, const bct_id_t block, cycle_t start_a
  * @retval PL_TLC_NOT_YET: まだ指定時刻になっていない or PacketList が空
  * @retval PL_PACKET_TYPE_ERR: 指定した PacketList の packet が CCP ではない
  */
-PL_ACK PL_check_tl_cmd(PacketList* pl, cycle_t time);
+PL_ACK PL_check_tl_cmd(const PacketList* pl, cycle_t time);
 
 #endif