Changeset 87b490e3 in mainline


Ignore:
Timestamp:
2024-12-13T08:44:05Z (15 months ago)
Author:
Nataliia Korop <n.corop08@…>
Children:
420b13d
Parents:
fb31682
git-author:
Nataliia Korop <n.corop08@…> (2024-11-30 19:08:32)
git-committer:
Nataliia Korop <n.corop08@…> (2024-12-13 08:44:05)
Message:

docs comments

Location:
uspace
Files:
12 edited

Legend:

Unmodified
Added
Removed

  • uspace/app/pcapctl/main.c

    rfb31682 r87b490e3  
    3030 * @{
    3131 */
    32 /** @file pcapctl app
     32/** @file pcapctl command-line utility.
    3333 */
    3434
    … …  
    4242#include "pcapdump_client.h"
    4343
    44 #define NAME "pcapctl"
    45 #define DEFAULT_DEV_NUM 0
    46 #define DECIMAL_SYSTEM 10
    47 
    48 #define DEFAULT_FILE_OPS 0
    49 #define SHORT_FILE_OPS 1
    50 #define APPEND_FILE_OPS 2
    51 #define USB_FILE_OPS 3
    52 
     44#define NAME                            "pcapctl"
     45#define DEFAULT_DEV_NUM         0
     46#define DECIMAL_SYSTEM          10
     47
     48/* Default writer operations for dumper, must be consistent with array defined in /uspace/lib/pcap/pcap_dumper.c */
     49#define DEFAULT_FILE_OPS        0
     50#define SHORT_FILE_OPS          1
     51#define APPEND_FILE_OPS         2
     52#define USB_FILE_OPS            3
     53
     54/** Create async session and send start request.
     55 *  @param dev_number index of the device that can dump packets.
     56 *  @param name of the output buffer.
     57 *  @param ops_index index of the writer operations for the dumper.
     58 *  @return EOK if all parameters are valid and start request was sent successfully, error code otherwise.
     59 */
    5360static errno_t start_dumping(int *dev_number, const char *name, int *ops_index)
    5461{
    … …  
    7784}
    7885
     86/** Create async session and send stop dumping request.
     87 *  @param dev_numbe index of the device on which the dumping will be stopped.
     88 *  @return EOK if request was sent successfully, error code otherwise.
     89 */
    7990static errno_t stop_dumping(int *dev_number)
    8091{
    … …  
    92103}
    93104
     105/** Print devices that can dump packets. */
    94106static void list_devs(void)
    95107{
    … …  
    101113 */
    102114static const struct option opts[] = {
    103         { "append", required_argument, 0, 'A' }, // file as argument and ops 0 if not exist and 2 if exists
    104         { "new", required_argument, 0, 'N' }, // file name as argument
     115        { "append", required_argument, 0, 'A' }, /* file as argument and ops 0 if not exist and 2 if exists */
     116        { "new", required_argument, 0, 'N' }, /* file name as argument */
    105117        { "truncated", required_argument, 0, 'T' }, // truncated ops
    106118        { "usb", required_argument, 0, 'U' }, //??
    … …  
    116128};
    117129
     130/** Check if the file exists.
     131 *  @param path of the file to check.
     132 *  @return true if exists, false otherwise.
     133 */
    118134static bool file_exists(const char *path)
    119135{
    … …  
    128144static void usage(void)
    129145{
    130         printf("Usage:\n"
     146        printf("HelenOS Packet Dumping utility.\n"
     147            "Usage:\n"
    131148            NAME " --list | -l \n"
    132149            "\tList of devices\n"
    … …  
    218235        }
    219236
    220         printf("%s: HelenOS Packet Dumping utility: device - %d, ops - %d.\n", NAME, dev_number, ops_number);
    221 
    222237        if (start) {
    223238
    … …  
    227242                }
    228243
     244                printf("Sarting dumping on device - %d, ops - %d.\n", dev_number, ops_number);
     245
    229246                /* start with dev number and name */
    230247                start_dumping(&dev_number, output_file_name, &ops_number);
    231248        } else if (stop) {
    232249                /* stop with dev number */
     250                printf("Stopping dumping on device - %d, ops - %d.\n", dev_number, ops_number);
    233251                stop_dumping(&dev_number);
    234252        } else {

  • uspace/lib/pcap/include/pcap.h

    rfb31682 r87b490e3  
    3333/**
    3434 * @file
    35  * @brief Headers and functions for .pcap file and packets to be dumped
     35 * @brief Headers and functions for PCAP format and packets to be dumped.
    3636 */
    3737
    … …  
    4646#include <errno.h>
    4747
    48 #define PCAP_MAGIC_MICRO 0xA1B2C3D4
    49 #define PCAP_MAGIC_NANO 0xA1B23C4D
    50 #define PCAP_MAJOR_VERSION 0x0002
    51 #define PCAP_MINOR_VERSION 0x0004
    52 #define PCAP_SNAP_LEN 0x00040000
     48#define PCAP_MAGIC_MICRO 0xA1B2C3D4 /** Sets time in seconds and microseconds in packet records. */
     49#define PCAP_MAGIC_NANO 0xA1B23C4D /** Sets time in seconds and nanoseconds in packet records. */
     50#define PCAP_MAJOR_VERSION 0x0002  /** Major version of the PCAP format. */
     51#define PCAP_MINOR_VERSION 0x0004  /** Miner version of the PCAP format. */
     52#define PCAP_SNAP_LEN 0x00040000  /** Maximum number of bytes that can be captured for one packet record. */
    5353
    5454#define PCAP_LINKTYPE_ETHERNET 1    /* IEEE 802.3 Ethernet */
    … …  
    5656#define PCAP_LINKTYPE_IEEE802_11_RADIO 127
    5757#define PCAP_LINKTYPE_USB_LINUX_MMAPPED 220
    58 #define WIRESHARK_EX 0xc
    59 #define WIRESHARK_SNAPLEN 0xffff
    6058
    6159/** Header of the .pcap file. */
    … …  
    8078typedef struct pcap_writer pcap_writer_t;
    8179
    82 /** Operations for dumper. */
     80/** Writing operations for destination buffer. */
    8381typedef struct {
    8482        errno_t (*open)(pcap_writer_t *, const char *);
    … …  
    8987} pcap_writer_ops_t;
    9088
    91 /** Interface for working with .pcap file. */
     89/** Structure for writing data to the destination buffer. */
    9290struct pcap_writer {
     91        /** Writing buffer. */
    9392        void *data;
     93        /** Writing operations for working with the buffer. */
    9494        pcap_writer_ops_t *ops;
    9595};

  • uspace/lib/pcap/include/pcap_dumper.h

    rfb31682 r87b490e3  
    3030 * @{
    3131 */
    32 /** @file pcap interface
     32/** @file Pcap dumper. Structure is a part of every device that is in category PCAP and can dump packets.
    3333 */
    3434
    … …  
    4040#include "pcap.h"
    4141
     42/** Packet dumper structure that is responsible for dumping packets. */
    4243typedef struct pcap_dumper {
    4344        fibril_mutex_t mutex;
     45        /** Flag that indicates, whether the packet should be dumped or ignored. */
    4446        bool to_dump;
     47        /** Writer structure that is responsible for writing data to the destination buffer. */
    4548        pcap_writer_t writer;
    4649} pcap_dumper_t;
    … …  
    5356
    5457#endif
     58
    5559/** @}
    5660 */

  • uspace/lib/pcap/include/pcapdump_client.h

    rfb31682 r87b490e3  
    3232 */
    3333/**
    34  * @file
     34 * @file Client side of the IPC communication for pcapctl.
    3535 *
    3636 */
    … …  
    4545#include <fibril_synch.h>
    4646
     47/** IPC session structure for pcapctl utility. */
    4748typedef struct {
    4849        async_sess_t *sess;

  • uspace/lib/pcap/include/pcapdump_drv_iface.h

    rfb31682 r87b490e3  
    3232 */
    3333/**
    34  * @file
     34 * @file Driver interface. Functions that are used in drivers that can dump packets.
    3535 *
    3636 */

  • uspace/lib/pcap/include/pcapdump_ipc.h

    rfb31682 r87b490e3  
    4141#include <ipc/common.h>
    4242
     43/** IPC requests for INTERFACE_PCAP_CONTROL interface. */
    4344typedef enum {
    4445        PCAP_CONTROL_SET_START = IPC_FIRST_USER_METHOD,

  • uspace/lib/pcap/include/pcapdump_srv.h

    rfb31682 r87b490e3  
    3232 */
    3333/**
    34  * @file
     34 * @file Server side of the IPC communication for dumping packets framework.
    3535 *
    3636 */

  • uspace/lib/pcap/src/pcap.c

    rfb31682 r87b490e3  
    11/*
    2  * Copyright (c) 2023 Nataliia Korop
     2 * Copyright (c) 2024 Nataliia Korop
    33 * All rights reserved.
    44 *
    … …  
    5353/** Add pcap file header to the new .pcap file.
    5454 *
    55  * @param writer writer that has destination buffer and ops to write to destination buffer.
    56  *
     55 * @param writer        Writer that has destination buffer and ops to write to destination buffer.
     56 * @param linktype      Linktype for the file header.
     57 * @param nano          True for nanoseconds, false for microseconds in timestamp.
    5758 */
    5859void pcap_writer_add_header(pcap_writer_t *writer, uint32_t linktype, bool nano)
    … …  
    6970/** Add packet to the .pcap file.
    7071 *
    71  * @param writer
    72  * @param captured_packet Packet to be dumped
    73  * @param size Size of the captured packet
     72 * @param writer                        Writer that has destination buffer and ops to write to destination buffer.
     73 * @param captured_packet       Packet to be dumped
     74 * @param size                          Size of the captured packet
    7475 *
    7576 */

  • uspace/lib/pcap/src/pcap_dumper.c

    rfb31682 r87b490e3  
    3030 * @{
    3131 */
    32 /** @file
    33  *  @brief pcap inteface: Dumping interface for the device which packets we want to dump
     32/** @file Pcap dumper. Structure is a part of every device that is in category PCAP and can dump packets.
    3433 */
    3534
    … …  
    4342/** Initialize writing to .pcap file.
    4443 *
    45  * @param writer    Interface for working with .pcap file.
     44 * @param writer    Interface for writing data.
    4645 * @param filename  Name of the file for dumping packets.
    47  * @return          EOK on success or an error code.
     46 * @return          EOK on success, otherwise an error code.
    4847 *
    4948 */
    … …  
    6665}
    6766
     67/** Open file for appending to the end of it.
     68 *  @param writer       Interface for writing data.
     69 *  @param filename Path to the file.
     70 *  @return             EOK on success, error code otherwise.
     71 */
    6872static errno_t pcap_writer_to_file_init_append(pcap_writer_t *writer, const char *filename)
    6973{
    … …  
    7680}
    7781
     82/** Initialize file for dumping usb packets.
     83 *  @param writer       Interface for writing data.
     84 *  @param filename Path to the file.
     85 *  @return             EOK on success, error code otherwise.
     86 */
    7887static errno_t pcap_writer_to_file_usb_init(pcap_writer_t *writer, const char *filename)
    7988{
    … …  
    94103}
    95104
     105/** Write 4B to the file.
     106 *  @param writer       Interface for writing data.
     107 *  @param data         Bytes to write.
     108 *  @return             Size of successfully witten data.
     109 */
    96110static size_t pcap_file_w32(pcap_writer_t *writer, uint32_t data)
    97111{
    … …  
    99113}
    100114
     115/** Write 2B to the file.
     116 *  @param writer       Interface for writing data.
     117 *  @param data         Bytes to write.
     118 *  @return             Size of successfully witten data.
     119 */
    101120static size_t pcap_file_w16(pcap_writer_t *writer, uint16_t data)
    102121{
    … …  
    104123}
    105124
     125/** Write block of bytes to the file.
     126 *  @param writer       Interface for writing data.
     127 *  @param data         Bytes to write.
     128 *  @param size         Size of block of bytes.
     129 *  @return             Size of successfully witten data.
     130 */
    106131static size_t pcap_file_wbuffer(pcap_writer_t *writer, const void *data, size_t size)
    107132{
    … …  
    110135}
    111136
     137/** Close file for writing.
     138 *  @param writer       Interaface for writing data.
     139 */
    112140static void pcap_file_close(pcap_writer_t *writer)
    113141{
    … …  
    116144}
    117145
     146/** Write <= 60B of block of bytes.
     147 *  @param writer       Interface for writing data.
     148 *  @param data         Bytes to write.
     149 *  @param size         Size of block of bytes.
     150 *  @return             Size of successfully witten data.
     151 */
    118152static size_t pcap_short_file_wbuffer(pcap_writer_t *writer, const void *data, size_t size)
    119153{
    … …  
    121155}
    122156
     157/** Standard writer operations for writing data to a newly created file. */
    123158static const pcap_writer_ops_t file_ops = {
    124159        .open = &pcap_writer_to_file_init,
    … …  
    129164};
    130165
     166/** Truncated writer operations. Only first 60 bytes of the packet are written. */
    131167static const pcap_writer_ops_t short_file_ops = {
    132168        .open = &pcap_writer_to_file_init,
    … …  
    138174};
    139175
     176/** Append writer operations. Instead of creating new file open existing file and append packets. */
    140177static const pcap_writer_ops_t append_file_ops = {
    141178        .open = &pcap_writer_to_file_init_append,
    … …  
    146183};
    147184
     185/** USB writer operations. Writing USB packets to the file. */
    148186static const pcap_writer_ops_t usb_file_ops = {
    149187        .open = &pcap_writer_to_file_usb_init,
    … …  
    154192};
    155193
     194/** Default array of operations. Must be consistens with constants in /uspace/app/pcapctl/main.c */
    156195static pcap_writer_ops_t ops[4] = { file_ops, short_file_ops, append_file_ops, usb_file_ops };
    157196
     197/** Get number of writer operations in @ref ops */
    158198int pcap_dumper_get_ops_number(void)
    159199{
    … …  
    161201}
    162202
     203/** Open destination buffer for writing and set flag for dumping.
     204 *  @param dumper       Structure responsible for dumping packets. Part of the driver.
     205 *  @param name         Name of the destination buffer to dump packets to.
     206 *  @return             EOK if successful, erro code otherwise.
     207 */
    163208errno_t pcap_dumper_start(pcap_dumper_t *dumper, const char *name)
    164209{
    … …  
    174219}
    175220
     221/** Set writer options for the writer.
     222 *  @param dumper       Structure responsible for dumping packets. Part of the driver.
     223 *  @param index        Index of the writer operations from array @ref ops.
     224 *  @return             EOK if successful, erro code otherwise.
     225 */
    176226errno_t pcap_dumper_set_ops(pcap_dumper_t *dumper, int index)
    177227{
    … …  
    183233}
    184234
     235/** Write packet to destination buffer.
     236 *  @param dumper       Structure responsible for dumping packets. Part of the driver.
     237 *  @param data         Packet data to write.
     238 *  @param size         Size of the packet.
     239 */
    185240void pcap_dumper_add_packet(pcap_dumper_t *dumper, const void *data, size_t size)
    186241{
    … …  
    196251}
    197252
     253/** Close destination buffer for writing and unset flag for dumping.
     254 *  @param dumper       Structure responsible for dumping packets. Part of the driver.
     255 */
    198256void pcap_dumper_stop(pcap_dumper_t *dumper)
    199257{

  • uspace/lib/pcap/src/pcapdump_client.c

    rfb31682 r87b490e3  
    3030 * @{
    3131 */
    32 /** @file
    33  * @brief Client side of the pcapctl. Functions are called from the app pcapctl
     32/** @file Client side of the pcapctl. Functions are called from the app pcapctl.
    3433 */
    3534
    … …  
    5251}
    5352
     53/** Get service based on the index of the device.
     54 *  @param index of the device.
     55 *  @param svc placeholder for service ide.
     56 *  @return EOK if successful, error code otherwise.
     57 */
    5458static errno_t pcapctl_cat_get_svc(int *index, service_id_t *svc)
    5559{
    … …  
    8084}
    8185
     86/** Check if the index is an index of valid device.
     87 *  @param index to check.
     88 *  @return EOK if device is valid, error code otherwise.
     89 */
    8290errno_t pcapctl_is_valid_device(int *index)
    8391{
    … …  
    105113}
    106114
     115/** Check if the index is an index of valid writer operations.
     116 * @param index to check.
     117 * @param sess  pcapctl session for IPC communictaion.
     118 */
    107119errno_t pcapctl_is_valid_ops_number(int *index, pcapctl_sess_t *sess)
    108120{
    … …  
    127139}
    128140
    129 /**
    130  *
    131  */
     141/** Get all devices that can dump packets. */
    132142errno_t pcapctl_list(void)
    133143{
    … …  
    160170}
    161171
    162 /**
    163  *
     172/** Start pcapctl IPC session.
     173 *  @param index        index of the device which can dump packets.
     174 *  @param rsess        placeholder for the session.
     175 *  @return                     EOK if successful, error code otherwise.
    164176 */
    165177errno_t pcapctl_dump_open(int *index, pcapctl_sess_t **rsess)
    … …  
    196208}
    197209
    198 /**
    199  *
     210/** Close pcapctl IPC session.
     211 *  @param sess Session to close.
     212 *  @return EOK if successful, error code otherwise.
    200213 */
    201214errno_t pcapctl_dump_close(pcapctl_sess_t *sess)
    … …  
    205218}
    206219
    207 /** Starting a new session for pcapctl
    208  *
    209  * @param name Name of the file to dump packets to
    210  * @param sess session to start
    211  * @return EOK on success or an error code
     220/** Send start request via IPC to start dumping.
     221 *
     222 * @param name  Name of the destination buffer to dump packets to.
     223 * @param sess  Session that is used for communication.
     224 * @return              EOK on success or an error code.
    212225 */
    213226errno_t pcapctl_dump_start(const char *name, int *ops_index, pcapctl_sess_t *sess)
    … …  
    233246}
    234247
    235 /** Finish current session for pcapctl
    236  *
    237  * @param sess Session to finish
    238  * @return EOK on success or an error code
     248/** Send stop request via IPC to start dumping.
     249 *
     250 * @param sess  Session that is used for communication.
     251 * @return              EOK on success or an error code.
    239252 */
    240253errno_t pcapctl_dump_stop(pcapctl_sess_t *sess)

  • uspace/lib/pcap/src/pcapdump_drv_iface.c

    rfb31682 r87b490e3  
    4848#define NAME "pcap"
    4949
    50 /** Initialize interface for dumping packets
    51  *
    52  * @param dumper Device dumping interface
    53  *
     50/** Initialize interface for dumping packets.
     51 * @param dumper        Device dumping interface.
     52 * @return                      EOK if successful, error code otherwise.
    5453 */
    5554static errno_t pcapdump_drv_dumper_init(pcap_dumper_t *dumper)
    … …  
    6766}
    6867
     68/** Initialize driver dumping functionality.
     69 *  @param dumper       Dumping interface of the driver.
     70 *      @return                 EOK if successful, error code otherwise.
     71 */
    6972errno_t pcapdump_init(pcap_dumper_t *dumper)
    7073{
    … …  
    8689}
    8790
    88 /** Dumping function for driver
     91/** Dumping function for driver.
    8992 *
    90  * Called every time, the packet is sent/recieved by the device
     93 * Called every time, the packet is sent/recieved by the device.
    9194 *
    92  * @param dumper Dumping interface
    93  * @param data The packet
    94  * @param size Size of the packet
     95 * @param dumper        Dumping interface.
     96 * @param data          The packet
     97 * @param size          Size of the packet.
    9598 *
    9699 */

  • uspace/lib/pcap/src/pcapdump_srv.c

    rfb31682 r87b490e3  
    4747#include "pcapdump_ipc.h"
    4848
     49/** Start dumping.
     50 *      @param icall    IPC call with request to start.
     51 *  @param dumper       Dumping interface of the driver.
     52 */
    4953static void pcapdump_start_srv(ipc_call_t *icall, pcap_dumper_t *dumper)
    5054{
    … …  
    8488}
    8589
     90/** Stop dumping
     91 *      @param icall    IPC call with request to stop.
     92 *  @param dumper       Dumping interface of the driver.
     93 */
    8694static void pcapdump_stop_srv(ipc_call_t *icall, pcap_dumper_t *dumper)
    8795{
    … …  
    9098}
    9199
     100/** Get number of accessibke writer operations.
     101 *      @param icall    IPC call with request to get number of accessible writer operations.
     102 */
    92103static void pcapdump_get_ops_num_srv(ipc_call_t *icall)
    93104{
    … …  
    99110}
    100111
     112/** Callback connection function. Accepts requests and processes them.
     113 *      @param icall    IPC call with request.
     114 *  @param arg          Dumping interface of the driver.
     115 */
    101116void pcapdump_conn(ipc_call_t *icall, void *arg)
    102117{
Note: See TracChangeset for help on using the changeset viewer.